Lecture 5

APDL Commands
16.0 Release

ANSYS Mechanical Advances

(Using Command Objects)
1 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0
 Chapter Overview
In this chapter, we will focus on the ANSYS Parametric Design Language (APDL)
A. APDL Commands

B. Log File

C. Parameters

D. Control Logic

2 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 A. APDL Commands
APDL Commands have the following properties:
• In the format of Command,Argument1,Argument2,… where the first word is the
command followed by a comma-separated list of arguments
• Not case sensitive
• If the command is longer than 4 characters, only the first four letters need to be typed
as long as the first four letters are unique
– The BCSOPTION command controls sparse direct solver settings. The user may type
BCSOPTION or BCSO or BCSOPT to execute this command
• Typically has default values for arguments. If the argument is not supplied or left blank,
the default value is substituted automatically
– The MODOPT command controls how many modes to extract in a modal analysis. Issuing
MODOPT,QRDAMP,20,,,ON will use the default values for the 3rd and 4th arguments (which
are the beginning and ending frequency range, defaulting to 0 to 1e8 Hz, respectively)

3 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … APDL Commands
Generally speaking, there are a few “groups” of APDL commands
• Commands that begin with a letter are standard APDL commands that typically perform
an action or define a setting
– For example, the SF command applies a surface load to a group of nodes
• Those starting with a forward slash / are often graphics or processor-related, although
some also relate to filename management
– The /CONTOUR command allows a user to change the min/max range of legend
• APDL Commands that begin with an asterisk * are often associated with control logic,
I/O tasks, or user interaction
– To write data to an external text file, the *VWRITE command would be used

4 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … APDL Commands and Help System
The user may click on the [Help] button in dialog boxes or type HELP,Command
in the Command Prompt to bring up the relevant, detailed help section from
the Commands Reference

5 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … APDL Commands and Help System
• The beginning of the help section indicates:
1. The command syntax
2. Short description of the command
3. What “processor” the command can be used in
4. Which ANSYS Products are supported

1. 3.

2. 4.

6 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … APDL Commands and Help System
• The help section continues with details on the arguments:
5. Description of the argument
6. Default values, if any, are indicated

5.

6.

7 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … APDL Commands and Help System
7. The Notes section gives additional details on the command usage
8. Product Restrictions, if applicable, are listed
9. The location of this command in the GUI is also shown

7.

8.

9.

8 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … APDL Commands and Help System
• One does not have to learn APDL commands directly. Instead, annotating
the log file will aid the user in determining necessary APDL commands to
perform an action.
• Dialog boxes also present the APDL commands in square brackets

9 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 B. Log File
The log file can be accessed from “Utility Menu > List > Files > Log File…”
• The file resides in the solver directory as “file.log”
• All actions, whether executed from the GUI or typed in the Command Prompt, are
recorded in the log file.

• Session Editor can also give access to the recorded APDL commands of the current
session.

10 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … Log File and Comments
APDL contains comments, some of which are shown in the log file:
• /COM, !, and C*** all designate the beginning of comments. Everything after that is
after these commands is ignored by ANSYS.
• /COM and C*** echoes the comment in the Output Window and/or Output File, useful
to provide feedback to the user
• ! produces a silent comment and can appear anywhere on a line

In the log file, Mechanical

APDL automatically
includes the software
version number as well as
date & time of run as a
comment.

Some commands, such

as exiting Mechanical
APDL, are recorded in the
log file but commented
11 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0
 … Log File and Comments
• Learning all of the APDL commands can be challenging. However, by
annotating the log file using a comment, the user can obtain ‘snippets’ of
APDL commands to perform actions they want
– First, enter a comment (preceded by !) in the Command Prompt
– Second, perform action using the GUI menus/dialog boxes
– Lastly, enter a comment to indicate end of action
– Commands in between comments can be used to perform action

By using comments, the log

file can be annotated.
The user can copy and paste
this highlighted section of
APDL commands to reverse
the black background to
white.

12 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 C. Parameters
• Parameters are variables which can be used
within Mechanical APDL
– Parameters may be used instead of actual
numbers/values in any dialog box or command
argument. This not only reduces the risk of a typo but
provides a basis for parametric modeling.
– Parameters can include numbers or strings. Moreover,
scalar or array parameters may be defined.

• Parameter naming convention:

– Parameter names can be alphanumeric with an
underscore
– Parameter names, as with APDL commands and
arguments, are not case-sensitive.

13 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … Defining Scalar Parameters
• Scalar parameters are variables which can
contain one value
– Numeric scalar parameters can contain real numbers.
There is no distinction between integers and reals.
This can also be in scientific notation.
– Character scalar parameters can contain up to eight
characters, enclosed in single quotes.

• Defining scalar parameters:

– Numeric scalar parameters are defined by
*SET,param,value or param=value
– Character scalar parameters are assigned values by
*SET,param,’text’ or param=‘text’

14 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … Using Scalar Parameters
• After being defined, scalar parameters can be used in an argument of any
APDL command, such as the one shown below:

– APDL command is BLOCK,,LENGTH,,HEIGHT,-WIDTH/2,WIDTH/2

• In some APDL commands, strings are required arguments. In this case,

forced substitution of parameters is possible:

– APDL command is /TITLE,Max stress is %MAXSEQV%

15 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … Operating on Scalar Parameters
• Scalar parameters can also be based on each other.
– WIDTH = HEIGHT - 3
– Note that this is a static, not dynamic, definition

• Common arithmetic operations and functions can be used.

Type: Example:
– Arithmetic: + - * / LENGTH=2 + 3*5
Note: there cannot be a space before * in equation
– Exponential: ** SQUARE = 2**4
Note: exponential operator are two asterisks, not a ^ caret sign
– Trig. functions: sin(x), acos(x), tanh(x) PI=ACOS(-1)
Note: Radians assumed but can be changed via *AFUN command
– Arith. functions: nint(x), sqrt(x), abs(x) INTGR=nint(3.4)
– Log functions: log10(x), exp(x) DIST=log(15)

• See *SET command help in the Commands Reference for a complete listing

16 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … Retrieving Scalar Parameters
• Another way to assign values to parameters is through the *GET command
(retrieve information from the database).
– “Utility Menu > Parameters > Get Scalar Data”

– APDL command: *GET,param,entity,ENTNUM,Item1,IT1NUM, …

• This command can be used to get almost any type of data from the
database, including results.
• As will be demonstrated later, this is a very useful way to obtain any input or
output data from the model.

17 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … Retrieving Scalar Parameters
• Besides using *GET to retrieve data, there are
some APDL commands called “*GET functions”
to do this more easily
– NX(n) returns the x-coordinate of node ID n in the active
CS.
For example, one can use NSEL,S,LOC,X,nx(5) to
select all nodes which have the same x-coordinate value as
node ID #5.
Parameters can also be assigned via PARAM=nx(5).
– UZ(n) returns the calculated displacement in the z-
direction for node n.
– NELEM(E,NPOS) returns the ID number of the node in the
NPOS position of element E.

• See “Appendix B. GET Function Summary” in the

APDL Programmer’s Guide in the Mechanical
APDL help for a complete listing.

18 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … Listing Scalar Parameters
• Defined parameters and their values can be listed:
– “Utility Menu > Parameters > Scalar Parameters…”

– “Utility Menu > List > Other > Parameters”

• APDL Command: *STATUS

19 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … Array Parameters
• Oftentimes, it may be necessary to get information about the mesh or
manipulate the results in some manner.
• Arrays become an efficient means of gathering and manipulating
information about the model. These are a logical extension of scalar
parameters.

20 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … Array Parameters
Array parameters allow the user to define a parameter which can contain
multiple values:
• Arrays can be the following:
– Vector (row)
– Matrix (row and column)
– Third-order tensor (row, column, and plane)
– Arrays are used like parameters but with an index:
MY_PARAMETER(3) or ANOTHER_PARM(3,5)

21 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … Array Parameters
• Regular arrays are discrete values. These can be used for any purpose, such
as retrieving nodal results.

• Tables are like arrays, but in-between values can be interpolated.

• Strings can be a series of up to 128-letter strings. These can be used to
retrieve and manipulate strings of information.

22 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … Array Parameters
There are two main uses for Tables:
• Define loads or boundary conditions that may be transient, spatially-varying, or
temperature-dependent
• Define varying properties of real constants for some elements
Mechanical uses tables to define all loads (expressed as time-, temperature-,
and/or spatially-dependent)

An example of a spatially-varying pressure

loading on the top of a block.
When applying loads in Mechanical APDL,
a table can be used. Use %param% to
supply the name of the table “param”
when defining tabular loads, such as
SF,all,PRES,%param%

23 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … Defining Array Parameters
• Defining arrays, tables, and strings is done via the *DIM command:
– Defining a 3D (10x6x4) array:
*DIM,myarray,ARRAY,10,6,4
– Defining a 4D table that is a function of x, y, z, and time:
*DIM,pressureload,TAB4,10,3,5,2,X,Y,Z,TIME
– Defining a 1D string (max 128 characters):
*DIM,mystring,STRING,128

• See the *DIM command in the Commands Reference for more details on the
syntax

24 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … Assigning Values to Arrays
• Arrays are assigned values by index number, with up to 10 array elements in
a comma-separated list per assignment
– For example, the following 2 lines of APDL commands defines the array XYZ, graphically shown
below:
XYZ(1)=59.5,42.494,-9.01,-8.98,-8.98,9.01,-30.6,51
XYZ(9)=-51.9,14.88,10.8,-10.8

• To refer to an array, simply use the index number,

such as XYZ(8) which would give the value of 51

25 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … Assigning Values to Tables
• Tables, on the other hand, have non-integer indices which are defined
by a 0th column
– To illustrate this, consider the table named “FORCE” below:
FORCE(1)=0,560,560,238.5,0
FORCE(1,0)=1E-6,.8,7.2,8.5,9.3

• To refer to a table array, simply use the same notation as earlier for a
regular array, although instead of using an integer index, use the
interpolation column. For indices outside of the defined range, the last
value will be used.
– FORCE(3.2) will return 560
𝟗 − 𝟖. 𝟓 × 𝟎 − 𝟐𝟑𝟖. 𝟓
– FORCE(9) will give 89.4375 = 𝟐𝟑𝟖. 𝟓 +
𝟗. 𝟑 − 𝟖. 𝟓
– FORCE(9.5) will return 0
– FORCE(7.85) will return ?

26 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … Assigning Values to Tables
• A more common way to define tables is by reading in values from a text file
that is comma-, space-, or tab-delimited via the *TREAD command
– Useful to import data from Excel into Mechanical APDL as a table array

ncolon=44
saut=0
*SREAD,newstr,tableau,txt,,,saut
*GET,nlignes,parm,newstr,dim,2
*DIM,temptab,table,nlignes-1,ncolon-1,,time
*TREAD,temptab,tableau,txt,,saut
27 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0
 … Assigning Values to Strings
• Strings can be given a value simply by referring to the first index
– MYSTRING(1)=‘Here is a long string’

• The use of any other index will replace the contents from that character
– If the above command was executed, then the following was issued:
MYSTRING(9)=‘changed text’
then the resulting string would be ‘Here is achanged text’

• Strings may be operated on with string functions:

– StrOut = STRSUB(Str1, nLoc,nChar)
Get the nChar substring starting at character nLoc in Str1
– StrOut = STRCAT(Str1,Str2)
Add Str2 at the end of Str1
– StrOut = JOIN('directory','filename','extension')
Produces a contiguous pathstring. e.g. directory/filename.ext

• See “Appendix B. GET Function Summary” in the APDL Programmer’s Guide in the
Mechanical APDL help for a complete listing.

28 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … Retrieving Array Values
• To retrieve array information from the database, the *VGET command can
be used:
– “Utility Menu > Parameters > Get Array Data …”
– APDL Command: *VGET,myparm(1),entity,entnum,item1,it1num,…

Example
Save the nodal deformations in
an array:

NUMCMP !Compress numbers

*GET,nb_nodes,NODE,0,count
*DIM,location,array,nb_nodes,3
*VGET,location(1,1),node,1,U,X
*VGET,location(1,2),node,1,U,Y
*VGET,location(1,3),node,1,U,Z

29 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … Operating on Arrays
• Similar to functions which can operate on values or parameters, arrays can
be manipulated in a similar manner
• Vector operations are performed on a single vector or on a single row of 2-D,
3-D, 4-D, or 5-D arrays:
– “Utility Menu > Parameters > Array Operations”

– *VOPER command is used to operate on two vectors with the result as one vector.
Adding or comparing vectors is an example where the output will be another vector.
– *VFUN command is used to operate on one vector with the result as one vector.
Taking the cosine of a vector is an example.
– *VSCFUN command is used to operate on one vector with the result as one scalar parameter.
Taking the sum, standard deviation, or max value of a vector is an example where the output is a
scalar parameter.

• Matrix operations using *MOPER, *MFUN, and *MFOURI are also available.

30 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … Operating on Arrays
• Example: Considering the two arrays A and B

*VOPER,C(1),A(1,2),ADD,B(1,1)

*VFUN,C(1),COS,A(1,3)

*VSCFUN,value,SUM,B(1,2) value = 15

31 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … Saving and Restoring Parameters
• Scalar, array, table, and string parameters are saved in the Mechanical
APDL database. However, a user may wish to save or restore parameters
separately from a file.
– “Utility Menu > Parameters > Save Parameters …”
– PARSAV command writes scalar or all parameters to a text file with a default file extension
.parm

– “Utility Menu > Parameters > Restore Parameters …”

– PARRES command reads all parameters saved in a specified .parm file and either adds or
replaces the current parameters in the Mechanical APDL database

PARSAV

PARRES

32 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 D. Control Logic
• Mechanical APDL has control logic to perform repetitive actions or to
execute commands based on some criteria. There are two main sets of
control logic:
– If-then statements
• *IF, *ELSEIF, *ELSE, *ENDIF, *RETURN
– Do loops
• *DO, *DOWHILE, *CYCLE, *EXIT, *ENDDO, *RETURN

33 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … *IF statements
*IF and *ENDIF enclose a block of commands which are executed if the criteria
concerning a parameter is satisfied.

• The flowchart on the right

shows a simple example
of using *IF and *ENDIF.
• *ELSEIF statements are used
to provide additional
criteria to compare against.
• The *ELSE command is used
as a ‘default’ execution block
if commands need to be
executed in the event that
none of the criteria are satisfied.

34 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … *IF statements
• The *IF and *ELSEIF statements usually compare a parameter and
whether it satisfies a criteria specified by EQ, NE, LT, GT, LE, GE,
ABLT,or ABGT. (A=B, !=, <, >, <=, >=, ||>||, ||<||)
– *IF,a,EQ,b,THEN
/com, Case is true.
*ELSEIF,c,EQ,d
/com, Case is true.
*ENDIF

• Multiple criteria can also be specified in the *IF statement. Instead of

THEN, use AND/OR/XOR, which allows more flexibility:
– *IF,a,EQ,b,OR,c,EQ,d,then
/com, Case is true.
*ENDIF

• The *IF statement is often used to compare the values of two

parameters or to compare the parameter with a known value:
– *IF,myparama,EQ,myparamb,THEN …
– *IF,myvalue,LT,4.4,THEN …

35 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … *DO Loops
• A series of actions can be performed repetitively by specifying it within the
*DO and *ENDDO commands.
– The basic syntax of the *DO loop is:
*DO,param,initial_value,final_value,increment.
The parameter PARAM takes on initial value specified and increments until it
reaches the final value.
– For example, *DO,I,16,25 will loop 10 times, incrementing the parameter “I” by 1 (default)
from 16 to 25.

• A similar looping capability can be achieved with *DOWHILE and *ENDDO

commands.
– *DOWHILE,parameter is the syntax of this command. As long as parameter is greater than
0.0 (“TRUE” value), the loop continues. However, when parameter is less than or equal to 0.0
(“FALSE” value), the loop terminates.

36 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0

 … Example
• Loop on all the nodes selected and find the maximum stress value :

/POST1
SET,last
*GET,nb_nodes,NODE,0,count
Nd_current = 0
Seqv_max = 0
*DO,I,1,nb_nodes
Nd_current = NDNEXT(Nd_current)
*GET,Seqv_current,NODE,Nd_current,S,EQV
*IF,Seqv_current,GT,Seqv_max,then
Seqv_max=Seqv_current
*ENDIF
*ENDDO

37 © 2015 ANSYS, Inc. March 23, 2016 Release 16.0