ANSYS Parametric Design Language Guide 18.2
ANSYS Parametric Design Language Guide 18.2
ANSYS Parametric Design Language Guide 18.2
ANSYS, ANSYS Workbench, AUTODYN, CFX, FLUENT and any and all ANSYS, Inc. brand, product, service and feature
names, logos and slogans are registered trademarks or trademarks of ANSYS, Inc. or its subsidiaries located in the
United States or other countries. ICEM CFD is a trademark used by ANSYS, Inc. under license. CFX is a trademark
of Sony Corporation in Japan. All other brand, product, service and feature names or trademarks are the property
of their respective owners. FLEXlm and FLEXnet are trademarks of Flexera Software LLC.
Disclaimer Notice
THIS ANSYS SOFTWARE PRODUCT AND PROGRAM DOCUMENTATION INCLUDE TRADE SECRETS AND ARE CONFID-
ENTIAL AND PROPRIETARY PRODUCTS OF ANSYS, INC., ITS SUBSIDIARIES, OR LICENSORS. The software products
and documentation are furnished by ANSYS, Inc., its subsidiaries, or affiliates under a software license agreement
that contains provisions concerning non-disclosure, copying, length and nature of use, compliance with exporting
laws, warranties, disclaimers, limitations of liability, and remedies, and other provisions. The software products
and documentation may be used, disclosed, transferred, or copied only in accordance with the terms and conditions
of that software license agreement.
ANSYS, Inc. and ANSYS Europe, Ltd. are UL registered ISO 9001: 2008 companies.
For U.S. Government users, except as specifically granted by the ANSYS, Inc. software license agreement, the use,
duplication, or disclosure by the United States Government is subject to restrictions stated in the ANSYS, Inc.
software license agreement and FAR 12.212 (for non-DOD licenses).
Third-Party Software
See the legal information in the product help files for the complete Legal Notice for ANSYS proprietary software
and third-party software. If you are unable to access the Legal Notice, contact ANSYS, Inc.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. iii
ANSYS Parametric Design Language Guide
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
iv of ANSYS, Inc. and its subsidiaries and affiliates.
ANSYS Parametric Design Language Guide
Index .......................................................................................................................................................... 97
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. v
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
vi of ANSYS, Inc. and its subsidiaries and affiliates.
List of Figures
2.1. Toolbar ................................................................................................................................................... 3
2.2. Adding a New Abbreviation .................................................................................................................... 4
2.3. Toolbar with New Button ........................................................................................................................ 5
3.1. A Graphical Representation of a 2-D Array ............................................................................................. 20
3.2. A Graphical Representation of a 3-D Array ............................................................................................. 20
3.3. A Graphical Representation of a 5-D Array ............................................................................................. 20
3.4. A Graphical Representation of a Table Array ........................................................................................... 22
3.5. An Example *VEDIT Dialog Box for an ARRAY ......................................................................................... 25
3.6. An Example *VEDIT Dialog Box for a TABLE ............................................................................................ 26
3.7. Example 1-D TABLE Array Dialog ........................................................................................................... 28
3.8. Example 2-D TABLE Array Dialog ........................................................................................................... 28
3.9. Example 3-D TABLE Array Dialog ........................................................................................................... 29
3.10.Time-History Forcing Function ............................................................................................................. 30
3.11. Example Plot Using *VPLOT,,arrayval(1,1),2 ......................................................................... 42
3.12. Example Plot Using *VPLOT,,tableval(1,1),2 ......................................................................... 42
3.13. Example Plot Using *VPLOT,table2(1),tableval(1,1),2 ..................................................... 43
3.14. Example Plot Using *VPLOT,tableval(1,0),tableval(1,1),2 ............................................ 43
3.15. Example Plot With User-specified Labels .............................................................................................. 44
4.1. 3-D Representation of a Complex Dense Matrix ..................................................................................... 47
5.1. Mechanical APDL Message Box for Unknown Command ........................................................................ 56
5.2. The Create Menu Dialog Box ................................................................................................................. 59
5.3. A Macro Created in a Text Editor ............................................................................................................ 60
5.4. A Sample If-Then-Else Construct ............................................................................................................ 66
6.1. An Example *ASK Dialog Box ................................................................................................................. 76
6.2. A Typical Multiple-Prompt Dialog Box .................................................................................................... 78
6.3. A Typical Status Dialog Box ................................................................................................................... 81
1. Example File Hierarchy of Records ............................................................................................................ 94
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. vii
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
viii of ANSYS, Inc. and its subsidiaries and affiliates.
List of Tables
5.1. _RETURN Values .................................................................................................................................... 70
1. *GET - Get Function Summary .................................................................................................................. 87
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. ix
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
x of ANSYS, Inc. and its subsidiaries and affiliates.
Chapter 1: Introducing APDL
APDL stands for ANSYS Parametric Design Language, a scripting language that you can use to automate
common tasks or even build your model in terms of parameters (variables). While all Mechanical APDL
commands can be used as part of the scripting language, the APDL commands discussed here are the
true scripting commands and encompass a wide range of other features such as repeating a command,
macros, if-then-else branching, do-loops, and scalar, vector and matrix operations.
While APDL is the foundation for sophisticated features, it also offers many conveniences that you can
use in your day-to-day analyses. In this guide we'll introduce you to the basic features - parameters;
macros; branching, looping, and repeating; and array parameters - and show you some simple examples.
As you become more adept at the language, you will begin to recognize applications for APDL in your
own environment.
• Working with the toolbar (p. 3): You can add frequently used Mechanical APDL functions or macros
to the Mechanical APDL toolbar by defining abbreviations, which are aliases (up to eight characters
long) for a Mechanical APDL command, GUI function name, or macro name.
• Using parameters (p. 7): Parameters are APDL variables (they are more similar to Fortran variables
than to Fortran parameters). Mechanical APDL uses two types of parameters: scalar and array.
• Using APDL Math for matrix manipulations (p. 45): APDL Math gives you access to matrix manipulation
routines, including fast and efficient solvers. APDL Math provides access to matrices and vectors on the
.FULL, .EMAT, .MODE and .SUB files, as well as other sources, so that you can read them in, manip-
ulate them, and write them back out or solve them directly. Both dense matrices and sparse matrices
can be manipulated using APDL Math.
• Understanding APDL as a macro language (p. 55), including creating a macro: You can record a frequently
used sequence of Mechanical APDL commands in a macro file (these are sometimes called command
files). Creating a macro enables you to, in effect, create your own custom Mechanical APDL command.
In addition to executing a series of Mechanical APDL commands, a macro can call GUI functions or pass
values into arguments.
• Interfacing with the GUI: (p. 75) Within a Mechanical APDL macro, you have several ways to access
components of the Mechanical APDL GUI (toolbar, dialog box, *ASK command, etc.).
• Encrypting macros (p. 83): Mechanical APDL provides the ability to encrypt macro files so that the
source is not "human-readable." Encrypted macros require an encryption key to run. You can either
place the encryption key explicitly (in readable ASCII) in the macro or you can set it in Mechanical APDL
as a global encryption key.
See the APDL Commands (p. 85) for a list of all APDL commands discussed in this guide.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 1
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
2 of ANSYS, Inc. and its subsidiaries and affiliates.
Chapter 2: Working with the Toolbar
You can add frequently used Mechanical APDL functions or macros to the Mechanical APDL toolbar by
defining abbreviations, which are aliases (up to eight characters long) for a Mechanical APDL command,
GUI function name, or macro name. You can also modify the toolbar and nest toolbar abbreviations,
The Mechanical APDL program provides two ways to use abbreviations. You can issue the abbreviation
(and execute the macro, command, etc. that it performs) by typing it at the beginning of a command
line. If you are using the Mechanical APDL GUI, you can also execute the macro or command by pressing
the appropriate button on the Mechanical APDL toolbar.
The toolbar shown in Figure 2.1: Toolbar (p. 3) contains buttons that correspond to existing abbrevi-
ations.
While some abbreviations, such as SAVE_DB, are predefined, the abbreviations the toolbar contains and
the functions they execute are up to you. A single toolbar can hold up to 100 abbreviations (you can
"nest" toolbars to extend this number). You can redefine or delete abbreviations at will; however, abbre-
viations are not automatically saved and must be explicitly saved to a file and reloaded for each
Mechanical APDL session.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 3
Working with the Toolbar
• Clicking OK automatically updates the toolbar (using the *ABBR command requires that you use the
Utility Menu> MenuCtrls> Update Toolbar menu item to make your new abbreviation appear on the
toolbar).
Abbr
The abbreviation name that will appear on the toolbar button. The name can contain up to eight characters.
String
The String argument is the name of the macro or command that Abbr represents. If String is the name of
a macro, the macro must be within the macro search path. For more information about using macros, see
APDL as a Macro Language. If String references a Mechanical APDL picking menu or dialog box (using
UIDL), then specify "Fnc_string." For example, in the abbreviation definitions for "QUIT" and "POWRGRPH"
shown above, "Fnc_/QUIT" and "Fnc_/GRAPHICS" are unique UIDL function names which identify the
Mechanical APDL picking menu or dialog box associated with the QUIT and POWRGRPH abbreviations
respectively. For more information about accessing UIDL functions, see Calling Dialog Boxes From a Macro.
String can contain up to 60 characters but cannot include any of the following:
The default Mechanical APDL toolbar has the following abbreviations predefined:
*ABBR, SAVE_DB, SAVE
*ABBR, RESUM_DB, RESUME
*ABBR, QUIT, Fnc_/EXIT
*ABBR, POWRGRPH, Fnc_/GRAPHICS
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
4 of ANSYS, Inc. and its subsidiaries and affiliates.
Nesting Toolbar Abbreviations
The new button is appended to the button bar as shown in the following figure.
Note
If any abbreviations already exist in the named file, the ABBSAV command overwrites them.
The format of the abbreviations file is the APDL commands that are used to create the abbreviations.
Thus, if you wish to edit a large set of buttons or change their order, you may find using a text editor
to be the most convenient method. For example, the following is the file that results from saving the
default toolbar buttons.
/NOPR
*ABB,SAVE_DB ,SAVE
*ABB,RESUM_DB,RESUME
*ABB,QUIT ,Fnc_/EXIT
*ABB,POWRGRPH,Fnc_/GRAPHICS
/GO
The *ABB commands (the abbreviated form of *ABBR) define the buttons. The /NOPR at the top turns
off echoing to the log file while the /GO at the bottom turns log file echoing on.
PREP_ABR will appear as a button on the toolbar. Clicking it will replace the existing buttons with the
set of buttons defined in the prep.abbr file.
By defining abbreviations to restore these files and including those abbreviations in the appropriate
files, you can have a virtually unlimited number of abbreviations in a given Mechanical APDL session.
You can even extend this concept and create your own menu hierarchy by nesting several abbreviation
files. If you implement such a hierarchy, it's a good practice to add an abbreviation as a "return" button
in each file to navigate back through the menus.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 5
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
6 of ANSYS, Inc. and its subsidiaries and affiliates.
Chapter 3: Using Parameters
Parameters are APDL variables (they are more similar to Fortran variables than to Fortran parameters).
It is not necessary to explicitly declare the parameter type. All numeric values (whether integer or real)
are stored as double-precision values. Parameters that are used but not defined are assigned a near-
zero, or "tiny," value of approximately 2-100. For example, if parameter A is defined as A=B, and B is not
defined, then A is assigned the tiny value.
Mechanical APDL uses two types of parameters: scalar and array. The first part of this chapter discusses
information that is applicable to both types. Starting with Array Parameters (p. 18), the information is
specific to array type parameters. APDL commands used to define parameters in general and array
parameters specifically are listed in Chapter 2 of the Command Reference.
Character strings (up to eight characters long) can be assigned to parameters by simply enclosing the
string in single quotes. APDL also provides several types of array parameters: numeric, character, string
and table (a special numeric type that automatically interpolates values).
You can use a parameter (instead of a literal number or character string) as an argument to any Mech-
anical APDL command; the parameter is evaluated and its current value is used for that argument. For
example, if you assign the value 2.7 to a parameter named AA and then issue the command
N,12,AA,4
Note
If array, table, or character parameters are used within a macro or input file, those parameters
should be dimensioned (if array or table) and defined within that macro or input file. If you
fail to follow this practice, Mechanical APDL generates error messages indicating that those
parameters are undefined. Mechanical APDL generates the error messages even if the para-
meters lie within unexecuted *IF statements, as parameter substitution occurs before the
branching for the *IF is checked.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 7
Using Parameters
Valid:
ABC
PI
X_OR_Y
Invalid:
• Avoid parameter names that match commonly used Mechanical APDL labels, such as:
• Parameter names ARG1 through ARG9 and AR10 through AR99 are reserved for local parameters.
Generally, local parameters are used in macros (see Local Variables). Use of these names as "regular"
parameters is not recommended.
• Parameter names must not match abbreviations defined with the *ABBR command. For more inform-
ation about abbreviations, see Adding Commands to the Toolbar.
• Do not begin parameter names with an underscore (_). This convention is reserved for parameters used
by the GUI and Mechanical APDL-provided macros.
• APDL programmers supporting an organization should consider naming their parameters with a trailing
underscore(_). These can be displayed as a group using the *STATUS command and deleted from
memory as a group through the *DEL command.
• Older Mechanical APDL-provided macro files may use parameter names that do not begin with an un-
derscore. Using these macros embedded in your own macros may cause conflicts if the same parameter
names are used.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
8 of ANSYS, Inc. and its subsidiaries and affiliates.
Defining Parameters
This capability was added specifically for those who are developing APDL macros for large audiences.
You can use this to build macros that your Mechanical APDL users and other macro programmers cannot
list.
You can either assign values to parameters or retrieve values provided by Mechanical APDL and store
these values in parameters. For retrieving values from Mechanical APDL, you can use either the *GET
command or the various in-line get functions. The following sections cover these subjects in detail.
You can use an "=" as a shorthand way of calling the *SET command (this is the most convenient
method). The format of the shortcut is Name = Value, where Name is the name assigned to the para-
meter and Value is the numeric or character value stored in that parameter. For character parameters,
the assigned value must be enclosed in single quotes and cannot exceed eight alphanumeric characters.
The following are examples of "=" in use:
ABC=-24
QR=2.07E11
XORY=ABC
CPARM='CASE1'
In the GUI, you can either type the "=" directly in the Mechanical APDL input window or in the "Selection"
field of the Scalar Parameter dialog (Utility Menu> Parameters> Scalar Parameters).
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 9
Using Parameters
It is a good practice to avoid assigning one or two character parameter names at startup to avoid
conflicts with Mechanical APDL command line options.
Note
Remember that Linux shells treat single quotes and many other non-alphanumeric characters
as special symbols. When defining character parameters, you must tell Linux not to interpret
the quotes by inserting a backslash (\) before the single quotes. For example, the following
defines a character parameter having the value `filename'.
If you use the Mechanical APDL Launcher to start Mechanical APDL, you can define parameters through
the Customization tab (using the -Name Value format described above).
If you are defining a large number of parameters at startup, you'll find it much more convenient to
define these in the start.ans file or through a separate file that you can load through the /INPUT
command instead of the command line.
• The *GET command, which retrieves a value from a specified item and stores it in a specified parameter.
• The in-line get functions, which can be used in operations. Each get function returns a specific value
from a specific item.
where
• Entity is a keyword for the item to be stored. Valid keywords are NODE, ELEM, KP, LINE, AREA, VOLU,
etc. For a complete list of valid keywords, see the *GET description in the Command Reference.
• ENTNUM is the number of the entity (or zero for all entities).
• Item1 is the name of an item for a particular entity. For example, if Entity is ELEM, Item1 is either
NUM (the highest or lowest element number in the selected set) or COUNT (the number of elements
in the set). (For a complete list of Item1 values for each entity type, see the *GET description in the
Command Reference.)
You can think of the *GET command as a path down a tree structure, from general to specific information.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
10 of ANSYS, Inc. and its subsidiaries and affiliates.
Defining Parameters
The following examples show the *GET command in use. The first command below gets the material
attribute (the MAT reference number) of element 97 and assigns it to parameter BCD:
*GET,BCD,ELEM,97,ATTR,MAT ! BCD = Material number of element 97
*GET,V37,ELEM,37,VOLU ! V37 = volume of element 37
*GET,EL52,ELEM,52,HGEN ! EL52 = value of heat generation in element 52
*GET,OPER,ELEM,102,HCOE,2 ! OPER = heat coefficient of element 102,face2
*GET,TMP,ELEM,16,TBULK,3 ! TMP = bulk temperature of element 16,face3
*GET,NMAX,NODE,,NUM,MAX ! NMAX = maximum active node number
*GET,HNOD,NODE,12,HGEN ! HNOD = value of heat generation at node 12
*GET,COORD,ACTIVE,,CSYS ! COORD = active coordinate system number
1. Issue the following command to assign the x-location of Node 1 to parameter L1.
*GET,L1,NODE,1,LOC,X
2. Issue a second *GET command to assign the x-location of Node 2 to parameter L2.
A shorter method is to use the node location "get function" NX(N), which returns the x-location of node
N. You can use it to calculate the MID location without setting intermediate parameters L1 and L2, as
is shown in the following example:
MID=(NX(1)+NX(2))/2
Get function arguments can themselves be parameters or other get functions. For instance, get function
NELEM(ENUM,NPOS) returns the node number in position NPOS for element ENUM. Combining functions
NX(NELEM(ENUM,NPOS)) returns the x-location of that node.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 11
Using Parameters
You can also access this information via Utility Menu> List> Other> Parameters or Utility Menu>
List> Status> Parameters> All Parameters.
Note
Any parameters beginning or ending in an underscore (_) are not shown by the *STATUS
command.
You can check the status of individual parameters by providing these as arguments to the *STATUS
command. The following example shows the status of the ABC parameter.
*STATUS,ABC
You can also check the status of specific parameters via Utility Menu> List> Other> Named Parameter
or Utility Menu> List> Status> Parameters> Named Parameters.
• Issue the "=" command, leaving the right-hand side of the command blank. For example, to delete the
QR parameter issue this command:
QR=
• Issue the *SET command, but do not specify a value for the parameter. For example, to delete the QR
parameter via the *SET command, issue the command as follows:
*SET,QR,
Setting a numeric parameter equal to zero does not delete it. Similarly, setting a character parameter
equal to empty single quotes (` `) or placing blanks within single quotes does not delete the parameter.
Note
• As arguments to any applicable command field (that is, where alphanumeric input is expected).
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
12 of ANSYS, Inc. and its subsidiaries and affiliates.
Substitution of Numeric Parametric Values
• As arguments to macro calls for *USE and for the "unknown command" macro. Any of the following
macro calls are allowed:
ABC='SX'
*USE,NAME,ABC
or
*USE,NAME,'SX'
DEF='SY'
NEWMACRO,DEF ! Calls existing macro file NEWMACRO.MAC
or
NEWMACRO,'SY'
Note
Defining the parameter after it is used in a command does not "update" the command in
most cases. (Exceptions are the commands /TITLE, /STITLE, *ABBR, and /TLABEL. See Forced
Substitution (p. 14) for more information.) For example:
Y=0
X=2.7
N,1,X,Y ! Node 1 at (2.7,0)
Y=3.5 ! Redefining parameter Y now does not update node 1
Conversely, you can force parameter substitution in titles, subtitles, and filenames by enclosing the
parameter name with percent signs (%). For example,
/TITLE, TEMPERATURE CONTOURS AT TIME=%TM%
specifies a title in which the numerical value of parameter TM is substituted. Note that the parameter
is substituted at the time the title is used.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 13
Using Parameters
• /TITLE command (Title field). Specifies titles for various printed output.
• /STITLE command (Title field). Specifies subtitles, similar to/TITLE. (You cannot access the /STITLE
command directly in the GUI.)
• Any filename or extension command argument. These arguments apply to commands such as /FILNAME,
RESUME, /INPUT, /OUTPUT, and FILE. (Direct parameter substitution is also valid in these fields.)
• Any 32 character field: A typical example is the name of macros. (Direct substitution is not valid for
these fields.)
• As a command name in any command name field. Also as an "unknown command" macro name in
field 1. For example:
R='RESUME'
%R%,MODEL,DB
The following example of the command input method shows forced substitution for a subtitle definition
and for a directory name.
A='TEST'
B='.RST'
C='/Mechanical APDL'
D='/MODELS/'
/STITLE,,RESULTS FROM FILE %C%%D%%A%%B%
SUBTITLE 1 =
RESULTS FROM FILE /Mechanical APDL/MODELS/TEST.RST
/POST1
FILE,A,RST,%C%%D% ! Read results from /Mechanical APDL/MODELS/TEST.RST
*ASK
This command may prompt you for an alphanumeric string (up to eight characters enclosed in single
quotes) which is assigned to a character scalar parameter. (You cannot access the *ASK command directly
in the GUI.)
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
14 of ANSYS, Inc. and its subsidiaries and affiliates.
Substitution of Numeric Parametric Values
*CFWRITE
This command writes Mechanical APDL commands to the file opened by *CFOPEN. It can be used to write
a character parameter assignment to that file. For example, *CFWRITE,B = 'FILE' is valid. (You cannot access
the *CFWRITE and *CFOPEN commands directly in the GUI.)
*MSG
Character parameters are allowed as input for the VAL1 through VAL8 arguments. The data descriptor
%C is used to indicate alphanumeric character data on the format line (which must follow the *MSG
command). The %C corresponds to the FORTRAN descriptor A8. (You cannot access the *MSG command
directly in the GUI.)
*VREAD
This command reads alphanumeric character data from a file and generates a character-array parameter.
The FORTRAN character descriptor (A) can be used in the format line which must follow the *VREAD
command.
*VWRITE
This command writes character parameter data to a file in a formatted sequence. The FORTRAN character
descriptor (A) can be used in the format line which must follow the *VWRITE command.
• Character parameter substitution is not allowed for the Par argument of the *SET, *GET, *DIM, and
*STATUS commands.
• Interactive editing of array parameters (*VEDIT command) is not available for character array parameters.
• Vector operation commands, such as *VOPER, *VSCFUN, *VFUN, *VFILL, *VGET, and *VITRP, do not
work with character array parameters.
• When operating on character parameters, the specification commands *VMASK and *VLEN are applic-
able only to the *VWRITE and *VREAD commands.
• Character parameters are not valid in parametric expressions which use addition, subtraction, multiplic-
ation, etc.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 15
Using Parameters
Example:
XYZ='CASE 1'
/TITLE,This is %XYZ%
APLOT
You can then change the value of XYZ and the new title appears on subsequent plots, even though
you did not reissue /TITLE.
XYZ='CASE 2'
Operator Operation
+ Addition
_ Subtraction
* Multiplication
/ Division
** Exponentiation
< Less-Than Comparison
> Greater-Than Comparison
You can also use parentheses for clarity and for "nesting" of operations, as shown above. The order in
which the Mechanical APDL program evaluates an expression is as follows:
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
16 of ANSYS, Inc. and its subsidiaries and affiliates.
Parametric Functions
Thus an expression such as Y2=A+B**C/D*E is evaluated in this order: B**C first, /D second, *E third,
and +A last. For clarity, you should use parentheses in expressions such as these. Parentheses can be
nested up to four levels deep, and up to nine operations can be performed within each set of paren-
theses. As a general rule, avoid using blank spaces between operators in expressions. In particular,
never include a blank space before the * character because the rest of the input line (beginning with
the *) is interpreted as a comment and is therefore ignored. (Do not use this convention as a comment;
use an exclamation point (!) for this purpose.)
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 17
Using Parameters
The parameters file is an ASCII file consisting largely of APDL *SET commands used to define the various
parameters. The following example shows the format of this file.
/NOPR
*SET,A , 10.00000000000
*SET,B , 254.3948750000
*SET,C ,'string '
*SET,_RETURN , 0.0000000000000E+00
*SET,_STATUS , 1.000000000000
*SET,_ZX ,' '
/GO
If you wish, you can write up to ten parameters or array parameters using FORTRAN real formats to a
file. You can use this feature to write your own output file for use in other programs, reports, etc. To
do this, use the *VWRITE command. The *VWRITE command is discussed in Operations Among Array
Parameters (p. 34).
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
18 of ANSYS, Inc. and its subsidiaries and affiliates.
Array Parameters
ARRAY
This type is similar to FORTRAN arrays and is the default array type when dimensioning arrays. As with
FORTRAN arrays, the indices for rows, columns, and planes are sequential integer numbers beginning
with one. Array elements can be either integers or real numbers.
CHAR
This is a character array, with each element consisting of an alphanumeric value not exceeding eight
characters. The indices for rows, columns, and planes are sequential integer numbers beginning with
one.
TABLE
This is a special type of numeric array which allows Mechanical APDL to calculate (through linear in-
terpolation) values between these array elements explicitly defined in the array. Moreover, you can
define the array indices for each row, column, and plane and these indices are real (not integer)
numbers. Array elements can be either integers or real numbers. As we'll see in the later discussion
on TABLE arrays, this capability provides a powerful method for describing mathematical functions.
STRING
You can use the *DIM, STRING capability to enter character strings into your arrays. Index numbers
for columns and planes are sequential values beginning with 1. Row indices are determined by the
character position in the string. See the *DIM command for more information.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 19
Using Parameters
We can extend these definitions to a 3-D array parameter, which may be m rows long, n columns wide,
and p planes deep. The plane index number is k, which varies from 1 to p. Each array element is iden-
tified as (i,j,k,). The following figure shows a 3-D array.
Column
Row
Plane 3
Plane 2
Plane 1
Column
Row
4-D
Book 1 Plane 3
Plane 2
Plane 1
Column
Row
Plane 3
Plane 2
Plane 1
5-D Shelf 1
Column
Row
4-D
Book 2 Plane 3
Plane 2
Plane 1
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
20 of ANSYS, Inc. and its subsidiaries and affiliates.
Array Parameters
The parameter NTEMP could be an array of temperatures at selected nodes; NTEMP(1) = -47.6 could be
the temperature at node 27, NTEMP(2) = -5.2 could be the temperature at node 43, and so on. Similarly,
EVOLUM could be an array of element volumes, and COMPSTRS could be an array of nodal component
stresses, with each column representing a particular direction (X, Y, Z, XY, YZ, XZ, for example).
A type CHAR array parameter is structured similarly to an ARRAY parameter, with the tabular values
being alphanumeric character strings (up to eight characters). Two examples of character array parameters
are:
• Mechanical APDL can calculate (through linear interpolation) any values that fall between the explicitly
declared array element values.
• A table array contains a 0 row and 0 column used for data-access index values, and unlike standard
arrays, these index values can be real numbers. The only restriction is that the index values must be
numerically increasing (never decreasing) numbers. You must explicitly declare a data access index
value for each row and column; otherwise the default value assigned is the "tiny number" (7.888609052E-
31).
You can more conveniently define the index starting point and index values via the *TAXIS
command.
• A plane index value resides in the 0,0 location for each plane.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 21
Using Parameters
The following figure shows a TABLE array with data-access index values. Note that the indexes are
specified as the "0" row and column values.
As shown in the above example, when configuring a table array you must set
• The plane index value as the 0,0 element value for each plane.
• The data-access column index values in the elements in the 0 row in plane 1. Only the column index
values from plane 1 are used when accessing data from the array for all planes. When setting the array
element values, you use the traditional row and column index numbers.
• The data-access row index values in the elements in the 0 column in plane 1. Only the row index values
from plane 1 are used when accessing data from the array for all planes. When setting the array element
values, you use the traditional row and column index numbers.
This following examples illustrate the *DIM command used to dimension various types of arrays:
*DIM,AA,,4 ! Type ARRAY is default, dimension 4[x1x1]
*DIM,XYZ,ARRAY,12 ! Type ARRAY array, dimension 12[x1x1]
*DIM,FORCE,TABLE,5 ! Type TABLE array, dimension 5[x1x1]
*DIM,T2,,4,3 ! Dimensions are 4x3[x1]
*DIM,CPARR1,CHAR,5 ! Type CHAR array, dimension 5[x1x1]
Note
Array elements for ARRAY and TABLE are initialized to 0 (except for the 0 row and column
for TABLE, which is initialized to the tiny value). Array elements for CHAR are initialized to a
blank value.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
22 of ANSYS, Inc. and its subsidiaries and affiliates.
Array Parameters
For array parameter operations (for example *VOPER, *VFUN), the resulting array parameter (ParR)
need not be dimensioned beforehand. Also, array parameters defined completely with the implied
(colon) loops convention (for example a(1:5)=10,20,30,40,50) need not be dimensioned beforehand.
The next example shows how to fill a 5-D array with data. Use 1-D tables to load a 5-D table. Use the
*TAXIS to define the table index values. See the full example at Example Analysis Using 5-D Table Array.
*dim,xval,array,X1
*dim,yval,array,Y1
yval(1)=0,20
*dim,zval,array,10
zval(1)=10,20,30,40,50,60,70,80,90,100
*dim,tval,array,5
tval(1)=1,.90,.80,.70,.60
*dim,tevl,array,5
tevl(1)=1,1.20,1.30,1.60,1.80
*dim,ccc,tab5,X1,Y1,Z1,D4,D5,X,Y,Z,TIME,TEMP
*taxis,ccc(1,1,1,1,1),1,0,wid !!! X-Dim
*taxis,ccc(1,1,1,1,1),2,0,hth !!! Y-Dim
*taxis,ccc(1,1,1,1,1),3,1,2,3,4,5,6,7,8,9,10 !!! Z-Dim
*taxis,ccc(1,1,1,1,1),4,0,10,20,30,40 !!! Time
*taxis,ccc(1,1,1,1,1),5,0,50,100,150,200 !!! Temp
*do,ii,1,2
*do,jj,1,2
*do,kk,1,10
*do,ll,1,5
*do,mm,1,5
ccc(ii,jj,kk,ll,mm)=(xval(ii)+yval(jj)+zval(kk))*tval(ll)*tevl(mm)
*enddo
*enddo
*enddo
*enddo
*enddo
• Setting individual array element values through the *SET command or "=" shortcut.
• Filling individual vectors (columns) in the array with either specified or calculated values (the *VFILL
command, for example).
• Interactively specifying values for the elements through the *VEDIT dialog.
Note
You cannot create or edit 4- or 5-D arrays interactively. *VEDIT, *VREAD, and *TREAD
are not applicable to 4- or 5-D arrays.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 23
Using Parameters
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
Notice that the starting location of the array element is indicated by the row index number of the
parameter (1 in the first command, 9 in the second command).
The following example shows how to define the element values for the 4x3 array parameter T2, dimen-
sioned earlier in the *DIM examples:
T2(1,1)=.6,2,-1.8,4 ! defines (1,1),(2,1),(3,1),(4,1)
T2(1,2)=7,5,9.1,62.5 ! defines (1,2),(2,2),(3,2),(4,2)
T2(1,3)=2E-4,-3.5,22,.01 ! defines (1,3),(2,3),(3,3),(4,3)
The following example defines element values for the TABLE array parameter FORCE discussed earlier.
FORCE(1)=0,560,560,238.5,0
FORCE(1,0)=1E-6,.8,7.2,8.5,9.3
The first “=” command defines the five array elements of the TABLE array FORCE. The second and third
“=” commands redefine the index numbers in the j=0 and i=0 row.
Character array parameters can also be defined using the "=" command. Assigned values can be up to
eight characters each and must be enclosed in single quotes. For example:
*DIM,RESULT,CHAR,3 !Character array parameter with dimensions (3,1,1)
RESULT(1)='SX','SY','SZ' !Assigns values to parameter RESULT
Notice that, as when defining a numerical array parameter, the starting location of the array element
must be specified (in this case, the row index number 1 is indicated).
Note
CHAR cannot be used as a character parameter name because it creates a conflict with the
CHAR label on the *DIM command. Mechanical APDL substitutes the character string value
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
24 of ANSYS, Inc. and its subsidiaries and affiliates.
Array Parameters
assigned to parameter CHAR when CHAR is input on the third field of the *DIM command
(Type field).
See the *VFILL command reference information in the Command Reference for more detail about the
command syntax. The following example illustrates the capabilities of the *VFILL command.
*DIM,DTAB,ARRAY,4,3 ! dimension 4 x 3 numeric array
*VFILL,DTAB(1,1),DATA,-3,8,-12,57 ! four data values loaded into vector 1
*VFILL,DTAB(1,2),RAMP,2.54,2.54 ! fill vector 2 with values starting at
! 2.54 and incrementing by 2.54
*VFILL,DTAB(1,3),RAND,1.5,10 ! fill vector 3 with random numbers between
! 1.5 and 10. Results vary due to
! random number generation.
• An initialize function to set any row or column to a specified value (ARRAY type only).
• Delete, copy, and insert functions for moving rows or columns of data (ARRAY type only).
Complete instructions for using the dialog are available from the box's Help button.
Note
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 25
Using Parameters
and an array called EXAMPLE that has been dimensioned as 2 x 3, the following commands (provided
as either a part or a macro or input listing)
*DIM,EXAMPLE,,2,3
*VREAD,EXAMPLE(1,1),dataval,,,JIK,3,2
(3F6.1)
result in
The *VREAD command cannot be issued directly from the command input window. However, the
Utility Menu> Parameters> Array Parameters> Read from File dialog offers a way to specify the
data descriptors and issue the command in interactive mode.
Note
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
26 of ANSYS, Inc. and its subsidiaries and affiliates.
Array Parameters
To read in a table of data from an external file, you still define the TABLE array first, specifying the
number of rows, columns, and planes, and the labels for each. You can then read an ASCII file containing
the table of data via the *TREAD command. At this time, you also specify the number of lines to skip
(NSKIP) between the top of the file and the first line of the table.
• The file containing the table of data can be created in a text editor or an external application (such as
Microsoft Excel), but it must be in ASCII form, tab-delimited, to be read into Mechanical APDL.
• You must first define the array in Mechanical APDL, remembering to allow for the index values (0,0).
• The values are read straight across the rows until all columns on each row of the array are filled;
Mechanical APDL then wraps from one row to the next and begins to fill those columns, and so on. Be
sure that the dimensions of the array you defined are correct. If you mistakenly define fewer columns
in the Mechanical APDL array than required, Mechanical APDL begins filling in the next row of the array
using the values remaining in the first row of the data table being read. Similarly, if you define more
columns in the Mechanical APDL array than required, Mechanical APDL fills all columns of the array
using values from the next row of the data table being read, and only then wrap and begin filling the
next row.
You can create 1-D, 2-D, and 3-D tables by reading data from an external file. Examples of how you
create each of these follows.
Note
Define a TABLE parameter "Tt" via the *DIM command. Specify four rows and one column, row label
of Time, and column label of Temp. The data table you created has four rows and one column of data,
plus the row and column index values (where the first column, TIME, is the row index values). Then,
read in the file, specifying two skipped lines. The TABLE array in Mechanical APDL looks like this:
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 27
Using Parameters
In Mechanical APDL, you define a TABLE parameter "Ttx" using the *DIM command. Specify four rows,
five columns, one plane, row label of TIME, and column label of X. The data table you created has four
rows and five columns of data, plus the row and column index values. Then, read in the file, specifying
two skipped lines. The TABLE array in Mechanical APDL looks like this:
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
28 of ANSYS, Inc. and its subsidiaries and affiliates.
Array Parameters
In the example above, the bold values (in the (0,0,Z) positions) indicate the separate planes. Each plane
of data, along with the row and column index values, is repeated for the separate planes. Only the
plane index value and the actual data values are different. The shaded area above shows the values
that change from plane to plane.
In Mechanical APDL, define a TABLE parameter "Ttxy" via the *DIM command. In the case of a 3-D table,
the table is dimensioned according to the number of rows, columns, and planes of data. The first column
(TIME) is the row index values and the first row is the column index values. Specify four rows, five
columns, two planes, row label of TIME, column label of X, and plane label of Y. The data table you
created has four rows and five columns of data in two planes, plus the row and column index values.
Then, read in the file, specifying two skipped lines. The TABLE array in Mechanical APDL looks like this
for the second plane of data (Y=1.5):
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 29
Using Parameters
As examples of how Mechanical APDL interpolates values in TABLE arrays, consider the following:
Given that A is a TABLE array parameter, the Mechanical APDL program can calculate any value between
A(1) and A(2), for example
This feature allows you to describe a function, such as y=f(x), using a TABLE array parameter. You would
use the j=0 column for values of the independent variable x and the "regular" j=1 column for values of
y. Consider, for example, a time-history forcing function described by five points as shown below.
You can specify this function as a TABLE array parameter whose array elements are the force values,
and whose row index numbers 1 through 5 are time values 0.0 through 9.3. Schematically, the parameter
then looks like this:
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
30 of ANSYS, Inc. and its subsidiaries and affiliates.
Array Parameters
Mechanical APDL can calculate (through linear interpolation) force values at times not specified in the
FORCE parameter. For the above example, Mechanical APDL calculates a value of 89.4375 for FORCE(9).
If a parameter location beyond the dimensions of the array is used, no extrapolation is done and the
end value is used. For example, Mechanical APDL provides a value of 560.0 for FORCE(5,2) or 0.0 for
FORCE(12)
You can see from these examples that TABLE array parameters can be very powerful tools in your ana-
lysis. Typical applications are time-history loading functions, response spectrum curves, stress-strain
curves, material-versus- temperature curves, B-H curves for magnetic materials, and so forth. Be aware
that TABLE array parameters require more computer time to process than the ARRAY type.
You must define a starting array location number for the array parameter the *VGET command creates.
Looping continues over successive entity numbers for the KLOOP default. For example,
*VGET,A(1),ELEM,5,CENT,X returns the centroid x-location of element 5 and stores the result in the first
location of A. Retrieving continues with elements 6, 7, and so on until successive array locations are
filled. In this example, if KLOOP is 4, then the centroid of x, y, and z are returned.
The *VPUT command uses the same arguments as the *VGET command (described above), but does
the opposite of the *VGET operation. For a list of valid labels for *VPUT items, see the command's de-
scription in the Command Reference.
The Mechanical APDL program "puts" vector items directly, without any coordinate system transformation.
*VPUT can replace existing array items, but can't create new items. Degree of freedom results that are
changed in the database are available for all subsequent operations. Other results change temporarily,
and are available mainly for immediately following print and display operations.
Note
Use this command with extreme caution, as it can alter entire sections of the database. The
*VPUT command doesn't support all items on the *VGET item list because putting values
into some locations could make the Mechanical APDL database inconsistent.
ABBREV STRING
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 31
Using Parameters
SAVE_DB SAVE
RESUM_DB RESUME
QUIT Fnc_/EXIT
POWRGRPH Fnc_/GRAPHICS
Mechanical APDLWEB Fnc_HomePage
LOCATION VALUE
5 1 1 -8.98000000
6 1 1 9.01000000
7 1 1 -30.6000000
8 1 1 51.0000000
9 1 1 -51.9000000
LOCATION VALUE
1 0 1 0.000000000E+00
2 0 1 0.800000000
3 0 1 7.20000000
4 0 1 8.50000000
5 0 1 9.30000000
1 1 1 0.000000000E+00
2 1 1 560.000000
3 1 1 560.000000
4 1 1 238.500000
5 1 1 0.000000000E+00
LOCATION VALUE
1 1 1 0.600000000
2 1 1 2.00000000
3 1 1 -1.80000000
4 1 1 4.00000000
1 2 1 7.00000000
2 2 1 5.00000000
3 2 1 9.10000000
4 2 1 62.5000000
1 3 1 2.000000000E-04
2 3 1 -3.50000000
3 3 1 22.0000000
4 3 1 1.000000000E-02
LOCATION VALUE
1 1 1 SX(CHAR)
2 1 1 SY(CHAR)
3 1 1 SZ(CHAR)
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
32 of ANSYS, Inc. and its subsidiaries and affiliates.
Array Parameters
those vectors to the currently open file (*CFOPEN command). The format for each vector is specified
with FORTRAN data descriptors on the line following the *VWRITE command (therefore you can't issue
the *VWRITE command from the Mechanical APDL input window.)
An array vector, specified with a starting element location (such as MYARRAY(1,2,1)). You can also use
an expression, which is evaluated as a constant value for that field in each row of the data file. The
keyword SEQU evaluates to a sequential column of integers, starting from one.
The format of each row in the data file is determined by the data descriptor line. You must include one
descriptor for each argument to the command. Do not include the word FORMAT in the descriptor line.
You can use any real format or character format descriptor; however, you may not use either integer
or list directed descriptors.
You must provide a data descriptor for each data item you specify as an argument to the *VWRITE
command. In general, you can use the F descriptor (floating point) for any numeric values. The F
descriptor takes the syntax
Fw.d
where
w
Is the width of the data field in characters.
d
Is the number of digits to the right of the decimal point.
Thus, for a field that is 10 characters wide and has eight characters after the decimal point, you would
use the following data descriptor:
F10.8
For character fields, you can use the A descriptor. The A descriptor has the syntax
Aw
where
w
Is the width of the data field in characters.
Thus, for a character field that is eight characters wide, the descriptor is
A8
The following examples illustrate the *VWRITE command and data descriptors in use.
Given that the MYDATA array has been dimensioned and filled with the following values:
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 33
Using Parameters
The following short macro first defines the scalar parameter X as having a value of 25 and then opens
the file vector (*CFOPEN command). The *VWRITE command then defines the data to be written to
the file. In this case, the first vector written uses the SEQU keyword to provide row numbers. Note that
in some cases that constants, scalar parameters, and operations that include array element values are
written to the file. Note the data file contents for these items.
x=25
*cfopen,vector
*vwrite,SEQU,mydata(1,1,1),mydata(1,2,1),mydata(1,3,1),10.2,x,mydata(1,1,1)+3
(F3.0,' ',F8.4,' ',F8.1,' 'F8.6,' ',F4.1,' 'F4.0,' 'F8.1)
*cfclos
The second example uses the following previously dimensioned and filled array:
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
34 of ANSYS, Inc. and its subsidiaries and affiliates.
Array Parameters
vector operation commands apply only to array parameters dimensioned (*DIM) as ARRAY type or
TABLE type.
The *VFILL, *VREAD, *VGET, *VWRITE, and *DIM commands were introduced earlier in this chapter.
Other commands that are discussed in this section include
*VOPER
Performs an operation on two input array vectors and produces a single output array vector.
*VFUN
Performs a function on a single input array vector and produces a single output array vector.
*VSCFUN
Determines the properties of a single input array vector and places the result in a specified scalar
parameter.
*VITRP
Forms an array parameter (type ARRAY) by interpolating an array parameter (type TABLE) at specified
table index locations.
The examples below illustrate the use of some of these commands. Refer to the Command Reference
for syntactical information about these commands. For all of the following examples, the array parameters
(of type ARRAY) X, Y, and THETA have been dimensioned and defined.
In the following example, the result array is first dimensioned (Z1). The *VOPER command then adds
column 2 of X to column 1 of Y, both starting at row 1, and then places the result into Z1. Notice that
the starting location (the row and column index numbers) must be specified for all array parameters.
The operation then progresses sequentially down the specified vector.
*DIM,Z1,ARRAY,4
*VOPER,Z1(1),X(1,2),ADD,Y(1,1)
In the following example, again the result array (Z2) is dimensioned first. The *VOPER command then
multiplies the first column of X (starting at row 2) with the fourth column of Y (starting at row 1) and
writes the results to Z2 (starting at row 1).
*DIM,Z2,ARRAY,3
*VOPER,Z2(1),X(2,1),MULT,Y(1,4)
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 35
Using Parameters
In this example, again the results array (Z4) is dimensioned first. The *VOPER command then performs
the cross product of four pairs of vectors, one pair for each row of X and Y. The i, j, and k components
of these vectors are columns 1, 2, and 3 respectively of X and columns 2, 3, and 4 of Y. The results are
written to Z4, whose i, j, and k components are vectors 1, 2, and 3 respectively.
*DIM,Z4,ARRAY,4,3
*VOPER,Z4(1,1),X(1,1),CROSS,Y(1,2)
In the following example, the results array (A3) is dimensioned first. The *VFUN command then raises
each element in vector 2 of X to the power of 2 and writes the results to A3.
*DIM,A3,ARRAY,4
*VFUN,A3(1),PWR,X(1,2),2
In this example, the results array (A4) is dimensioned. The two *VFUN commands then calculate the
cosine and sine of array elements in THETA and place the results in the first and second columns, re-
spectively, of A4. Notice that A4 now represents a circular arc spanning 90°, described by seven points
(whose x, y, and z global Cartesian coordinates are the three vectors). The arc has a radius of 1.0 and
lies parallel to the x-y plane at z = 2.0.
*DIM,A4,ARRAY,7,3
*AFUN,DEG
*VFUN,A4(1,1),COS,THETA(1)
*VFUN,A4(1,2),SIN,THETA(1)
A4(1,3)=2,2,2,2,2,2,2
In this example, the results array (A5) is first dimensioned. Then, the *VFUN command calculates the
tangent vector at each point on the curve represented by A4, normalizes it to 1.0, and places the results
in A5.
*DIM,A5,ARRAY,7,3
*VFUN,A5(1,1),TANG,A4(1,1)
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
36 of ANSYS, Inc. and its subsidiaries and affiliates.
Array Parameters
Two additional *VOPER operations, gather (GATH) and scatter (SCAT), are used to copy values from
one vector to another based on numbers contained in a "position" vector. The following example
demonstrates the gather operation. Note that, as always, the results array must be dimensioned first.
In the example, the gather operation copies the value of B1 to B3 (using the index positions specified
in B2). Note that the last element in B3 is 0 as this is its initialized value.
*DIM,B1,,4
*DIM,B2,,3
*DIM,B3,,4
B1(1)=10,20,30,40
B2(1)=2,4,1
*VOPER,B3(1),B1(1),GATH,B2(1)
*MOPER
Performs matrix operations on one or more input array parameter matrices and produces an output
array parameter matrix. Some of the available matrix operations are:
• Matrix multiplication
*MFUN
Copies or transposes an array parameter matrix (accepts one input matrix and produces one output
matrix).
*MFOURI
Calculates the coefficients for or evaluates a Fourier series.
The examples below illustrate the use of some of these commands. Refer to the Command Reference
for syntactical information about these commands.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 37
Using Parameters
This example shows the sorting capabilities of the *MOPER command. For this example, assume that
the array (SORTDATA) has been dimensioned and its element values have been defined as follows:
First, the OLDORDER array is dimensioned. The *MOPER command places the original order of the rows
into OLDORDER. The *MOPER command then sorts the rows in SORTDATA so that the 1,1 vector is now
in ascending order.
*dim,oldorder,,5
*moper,oldorder(1),sortdata(1,1),sort,sortdata(1,1)
To put the SORTDATA array back into its original order, you could then issue the following command:
*moper,oldorder(1),sortdata(1,1),sort,oldorder(1,1)
In the following example, the *MOPER command solves a set of simultaneous equations. The following
two arrays have been dimensioned and their values assigned:
The *MOPER command can solve a set of simultaneous equations for a square matrix. The equations
take the form
In the case of the above arrays, the *MOPER command solves the following set of simultaneous equa-
tions:
To solve the equations, first the results array (C) is dimensioned. Then the *MOPER command solves
the equations, using A as the matrix of a coefficients and B as a vector of b values.
*DIM,C,,4
*MOPER,C(1),A(1,1),SOLV,B(1)
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
38 of ANSYS, Inc. and its subsidiaries and affiliates.
Array Parameters
The following example shows the *MFUN command used to transpose data in an array. For this example,
assume that the array (DATA) was dimensioned and filled with the following values:
As always, the results array (DATATRAN) is dimensioned first, then the *MFUN command transposes
the values and writes them to DATATRAN.
*DIM,DATATRAN,,2,3
*MFUN,DATATRAN(1,1),TRAN,DATA(1,1)
Important: All specification commands are reset to their default settings after each vector or matrix
operation.
*VCUM
Specifies whether results are cumulative or noncumulative (overwriting previous results). ParR, the
result of a vector operation, is either added to an existing parameter of the same name or overwritten.
The default is noncumulative results, that is, ParR overwrites an existing parameter of the same name.
*VABS
Applies an absolute value to any or all of the parameters involved in a vector operation. The default
is to use the real (algebraic) value.
*VFACT
Applies a scale factor to any or all of the parameters involved in a vector operation. The default scale
factor is 1.0 (full value).
*VCOL
Specifies the number of columns in matrix operations. The default is to fill all locations of the result
array from the specified starting location.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 39
Using Parameters
*VSTAT
Lists the current specifications for the array parameters.
*VLEN
Specifies the number of rows to be used in array parameter operations.
*VMASK
Specifies an array parameter as a masking vector.
The following table lists the various specification commands and the vector and matrix array commands
that they affect.
*VLEN
*VABS *VFACT *VCUM *VCOL *VMASK
,NROW,NINC
*MFOURI No No No No No No No
*MFUN Yes Yes Yes No Yes No Yes
*MOPER Yes Yes Yes No Yes No Yes
*VFILL Yes Yes Yes N/A Yes Yes Yes
*VFUN Yes Yes Yes N/A Yes Yes Yes
*VGET Yes Yes Yes N/A Yes Yes Yes
*VITRP Yes Yes Yes N/A Yes Yes Yes
*VOPER Yes Yes Yes N/A Yes Yes Yes
*VPLOT No No N/A N/A Yes Yes Yes
*VPUT Yes Yes No N/A Yes Yes Yes
*VREAD Yes Yes Yes N/A Yes Yes Yes
*VSCFUN Yes Yes Yes N/A Yes Yes Yes
*VWRITE No No N/A N/A Yes Yes Yes
The examples below illustrate the use of some of the specification commands. Refer to the Command
Reference for syntactical information about these commands.
In the following, the results array (CMPR) is dimensioned. The two *VFUN commands, in conjunction
with the preceding *VMASK and *VLEN commands, then compress selected data and write them to
specified locations in CMPR. The complement to the COMP operation is the EXPA operation on the
*VFUN command.
*DIM,CMPR,ARRAY,4,4
*VLEN,4,2! Do next *V---- operation on four rows,
! skipping every second row
*VFUN,CMPR(1,2),COMP,Y(1,1)
*VMASK,X(1,3)!Use column 3 of X as a mask for next *V----
! operation
*VFUN,CMPR(1,3),COMP,Y(1,2)
This example uses the *VFACT command to round the values in an array vector to the number of
decimal places specified by the NUMDP scalar parameter (set to 2 in the example). The NUMDATA array
has been dimensioned and filled with the following values:
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
40 of ANSYS, Inc. and its subsidiaries and affiliates.
Array Parameters
numdp=2
*vfact,10**numdp
*vfun,numdata(1),copy,numdata(1)
*vfun,numdata(1),nint,numdata(1)
*vfact,10**(-numdp)
*vfun,numdata(1),copy,numdata(1)
This example uses the *VLEN and *VMASK commands to find the set of prime numbers less than 100.
An array, MASKVECT, is created using 1.0 to indicate that the row value is a prime number and 0.0 to
indicate that the value isn't prime. The algorithm used to create the mask vector is to initialize all rows
whose value is greater than 1 to 1.0 and then loop through the range of possible factors, eliminating
all multiples of the factor. The *VLEN command sets the row increment for performing operations to
FACTOR. When the *VFILL command is processed, the row number is incremented by this value. Because
the starting row is FACTOR x 2, the rows are processed by each loop in the following manner: FACTOR
x 2, FACTOR x 3, FACTOR x 4, etc.
*dim,maskvect,,100
*vfill,maskvect(2),ramp,1
*do,factor,2,10,1
*vlen,,factor
*vfill,maskvect(factor*2),ramp,0
*enddo
*vmask,maskvect(1)
*dim,numbers,,100
*vfill,numbers(1),ramp,1,1
*status,numbers(1),1,10
The resultant output from the *STATUS command, showing the first 10 elements in NUMBERS is:
PARAMETER STATUS- NUMBERS ( 5 PARAMETERS DEFINED)
(INCLUDING 2 INTERNAL PARAMETERS)
LOCATION VALUE
1 1 1 0.000000000E+00
2 1 1 2.00000000
3 1 1 3.00000000
4 1 1 0.000000000E+00
5 1 1 5.00000000
6 1 1 0.000000000E+00
7 1 1 7.00000000
8 1 1 0.000000000E+00
9 1 1 0.000000000E+00
10 1 1 0.000000000E+00
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 41
Using Parameters
The following demonstrates some of the capabilities of the *VPLOT command. For this example, two
TABLE arrays (TABLEVAL and TABLE) and one numeric array have been dimensioned and filled with the
following values:
The following are example *VPLOT commands and their resulting plots. Note that since ARRAY data is
unordered it is plotted as a histogram; TABLE data is ordered and is therefore plotted as a curve.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
42 of ANSYS, Inc. and its subsidiaries and affiliates.
Array Parameters
The example below uses the /GCOLUMN command at the beginning of the program input to apply
the labels “string01” and “string02” to the array curve.
/gcol,1,string01
/gcol,2,string02
*dim,xxx,array,10
*dim,yyy,array,10,2
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 43
Using Parameters
yyy( 1,1) = 1
yyy( 2,1) = 4
yyy( 3,1) = 9
yyy( 4,1) = 16
yyy( 5,1) = 25
yyy( 6,1) = 36
yyy( 7,1) = 49
yyy( 8,1) = 64
yyy( 9,1) = 81
yyy(10,1) = 100
yyy( 1,2) = 1
yyy( 2,2) = 2
yyy( 3,2) = 3
yyy( 4,2) = 4
yyy( 5,2) = 5
yyy( 6,2) = 6
yyy( 7,2) = 7
yyy( 8,2) = 8
yyy( 9,2) = 9
yyy(10,2) = 10
*vplo,xxx(1,1), yyy(1,1) ,2
The labels can be returned to the default value (COL 1 and COL 2) by issuing the /GCOLUMN command
with no string specified.
/gcol,1
/gcol,2
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
44 of ANSYS, Inc. and its subsidiaries and affiliates.
Chapter 4: APDL Math
APDL Math extends the APDL scripting environment of Mechanical APDL to give you access to the
powerful matrix manipulation routines in the Mechanical APDL product, including its fast and efficient
solvers. APDL Math provides access to matrices and vectors on the .FULL, .EMAT, .MODE and .SUB
files, as well as other sources, so that you can read them in, manipulate them, and write them back out
or solve them directly. This functionality augments the vector and matrix operations (such as *VOPER
and *MOPER), in the standard APDL scripting environment. Both dense matrices and sparse matrices
can be manipulated using APDL Math.
Differences Between Standard APDL and APDL Math APDL Math works in its own workspace inde-
pendent of the APDL environment. However, APDL arrays (vectors or matrices) may be imported into
this workspace for manipulation, and also may be exported from this workspace into the standard APDL
environment.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 45
APDL Math
• Generate matrices and vectors directly using APDL (*DIM, *SET, etc.).
• Mechanical APDL generates the matrices and vectors for you. These may come from a prior
solution or may have been generated using the WRFULL command. The matrices are obtained
from the .FULL, .EMAT, .SUB, .MODE or .RST files.
Once the files are available, you may import them into APDL Math using *DMAT for dense matrices,
*SMAT for sparse matrices, and *VEC for vectors.
You can use the linear matrix operators *MULT and *AXPY to combine specified matrices and, thus,
create other matrices. You may also modify the contents of matrices directly by using APDL expres-
sions; for example, "A(3,2)=6.4".
Additionally, you can use these steps to modify the matrices using standard APDL operations:
b. Modify the matrix using standard APDL operations such as *SET, *MOPER, *VFUN, *DO, etc.
c. Re-import the matrix back into APDL Math via *DMAT,,,IMPORT,APDL (or *VEC,,,IMPROT,APDL
for a vector).
The modified matrices may be used in standard Mechanical APDL solutions, solved in APDL Math,
or exported for use in an external application, as follows.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
46 of ANSYS, Inc. and its subsidiaries and affiliates.
Accessing Complex Scalar Values
– The simplest approach is to export the matrix as a superelement (*EXPORT,,SUB) for use in any
analysis.
– Once you do these steps, you can use *ITENGINE to use a PCG algorithm to find new solutions
to a perturbed matrix (for instance, for parametric or sensitivity studies).
• Export for use in an external application using *EXPORT with the Harwell-Boeing or Matrix Market
formats.
• For an example matrix named “MyMatrix”, the APDL parameters MyMatrix_rowDim and MyMatrix_colDim
are automatically created.
• For matrices imported from the .FULL file, the APDL parameter MyMatrix_NUMDOF is automatically
created, where NUMDOF is the number of degrees of freedom per node.
• For an example vector named “MyVector”, the APDL parameter MyVector_Dim is automatically created.
These APDL parameters are updated each time you manipulate these objects using APDL Math com-
mands.
A complex dense matrix is a 2-D array of complex scalars. It can also be considered a 3-D array of real
values as shown in the figure below:
Im Im Im
Re Re Re
Im
a 11 a 12 a 13 a 11 a 12 a 13 Re
Im
A= a 21 a 22 a 23 <=> A= a 21 a 22 a 23 Re
Im
a 31 a 32 a 33 a 31 a 32 a 33 Re
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 47
APDL Math
The examples outlined below show several ways to access the complex scalar values.
• To get the real part of a dense matrix term, you can use the syntax:
VAL_RE = A(i,j,1)
VAL_IM = A(i,j,2)
• You can also set a new value directly, using the same logic:
A(i,j,1) = 3.5
A(i,j,2) = 0.0
1. The user ordering is based on the user's node numbers. As an example, this ordering corresponds to
what would be printed in the POST1 postprocessor by the PRNSOL,U command.
2. The internal ordering is obtained by compressing the unused node numbers from the user's set and
renumbering them based on the reordered element set. This reordering is performed to obtain better
cache performance as these items are referenced in the solution phase. The map between the user
ordering and this internal ordering is referred to as the "nodal equivalence table" in the descriptions
of binary data files (see Format of Binary Data Files in the Programmer's Reference).
3. The solver ordering is obtained by reordering the equations (DOFs) in order to minimize the solver
time and disk requirements. Also, the effects of any constraints (D command), couplings (CP command),
and constraint equations (CE command or MPC contact) are accounted for, thereby reducing the DOF
set. This ordering, also referred to as the BCS ordering, represents the "independent" DOFs of the
system.
The matrices and load vector imported from the .FULL file (*SMAT,,,FULL) are in terms of the BCS or-
dering; mapping from the internal ordering to this ordering is required when working with these
matrices.
The resulting solution from *LSBAC will also be in this BCS ordering.
The mode shapes from the .MODE file and the DOF results from the .RST file are in the internal ordering,
and they need to be converted before use with any of the matrices from the .FULL file, as shown below:
*SMAT,Nod2Bcs,D,IMPORT,FULL,file.full,NOD2BCS ! import the mapping vector
*DMAT,PhiI,D,IMPORT,MODE,file.mode ! import the mode shapes
*MULT,Nod2Bcs,,PhiI,,PhiB ! convert to the BCS set
To convert from BCS to internal ordering (for example, after an *LSBAC solution), use the transpose of
the NOD2BCS mapping vector:
*MULT,Nod2Bcs,TRAN,Xbcs,,Xint
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
48 of ANSYS, Inc. and its subsidiaries and affiliates.
Creating a User Superelement
To convert from external (user) ordering to the internal ordering, use the FORWARD nodal mapping
vector. The following example retrieves the UZ displacement of user node 45232 from the internal
solution vector Xint:
*VEC,MapForward,I,IMPORT,FULL,file.full,FORWARD
j = MapForward(45232)
UzVal = Xint((j-1)*NUMDOF + 3) ! 3 is the UZ DOF number
To convert from internal ordering to external (user), use the BACK nodal mapping vector. The following
example puts a force at node 672 in the FX direction into Fint:
*VEC,MapBack,I,IMPORT,FULL,file.full,BACK
j = MapBack(672)
Fint((j-1)*NUMDOF + 1) = -1000
Importing from existing .SUB files or from NASTRAN DMIG files is straightforward. These matrices can
be modified using existing APDL or APDL Math operations and the modified matrix exported to a new
.SUB file. Note that for a DMIG file export, you must supply the nodal coordinates.
Creating a .SUB file from scratch requires additional information. You must create (*DIM) an m x 2 array,
where "m" is the number of master DOFs (rows in the matrix). In the first column, put the node number
of the master DOF, and in the second column put the DOF number. This array is then passed to the
*EXPORT,,SUB command. For example:
/prep7
! Provide coordinates for SUB file
N,11
N,12,1
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 49
APDL Math
• You cannot directly modify a sparse matrix in APDL Math. You must export it from APDL Math to
modify it:
• When working with matrices and vectors, care must be taken to insure that any operations are done
using consistent ordering (see Degree of Freedom Ordering (p. 48)).
Example 4.2: Read a Matrix and a Load Vector from a FULL File and Solve
! READ THE STIFFNESS MATRIX FROM THE FULL FILE
*SMAT,MatK,D,IMPORT,FULL,file.full,STIFF
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
50 of ANSYS, Inc. and its subsidiaries and affiliates.
APDL Math Examples
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 51
APDL Math
*PRINT,EiV
FINISH
Example 4.6: Import a Matrix from a .SUB File, Modify the Values, and Update the File
! LOAD THE K MATRIX FROM A SUB FILE
*DMAT,MatK,D,IMPORT,SUB,file.sub,STIFF
*PRINT,MatK
APDLMath is used to calculate the CMCC based on Equation 3.1 in the Mechanical APDL Structural Ana-
lysis Guide. The real modes are read from the Jobname.MODESYM mode file, the mass matrix from the
file.full file, and the complex modes from the Jobname.MODE file. The resulting CMCC are printed
out in the ASCII file Cmcc.txt. If the file Cmcc.txt already exists, the new coefficients will be appended
to this file.
! ------------------------------------------------------------
! GET THE MASS MATRIX FROM FILE.FULL
! ------------------------------------------------------------
*SMAT,Mass,D,IMPORT,FULL,file.full,MASS
! GET THE FULL TO BCS MAPPING
*SMAT,NodToBcs,D,IMPORT,FULL,file.full,NOD2BCS
! ------------------------------------------------------------
! GET THE COMPLEX MODES FROM FILE.MODE : PhiC
! ------------------------------------------------------------
*DMAT,PhiF,Z,IMPORT,MODE,file.mode,1,300
*MULT,NodToBcs,,PhiF,,PhiC
*FREE,PhiF
! ------------------------------------------------------------
! GET THE REAL MODES FROM FILE.MODESYM : PhiR
! ------------------------------------------------------------
*DMAT,PhiF,,IMPORT,MODE,file.modesym,1,300
*MULT,NodToBcs,,PhiF,,PhiR
*FREE,PhiF
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
52 of ANSYS, Inc. and its subsidiaries and affiliates.
APDL Math Examples
! ------------------------------------------------------------
! COMPUTE AND NORMALIZE THE CMCC : PhiR(T).M.PhiC
! ------------------------------------------------------------
Example 4.8: Import Matrices from Nastran DMIG Files and Create SUB Files for Mechanical APDL
! DEFINITION OF NODES, ELEMENTS
....
Nodes must be defined in Mechanical APDL to match Nastran Data to the Mechanical APDL model.
! IMPORT A STIFFNESS MATRIX FROM A NASTRAN DMIG FILE
*DMAT,KMat,D,IMPORT,DMIG,fileK.dmig
KMat(1,1) = KMat(1,1)*2
...
The two matrices are dumped into one single SUB file. The file is generated at the "DONE" keyword.
Example 4.9: Calculate the Participation Factors and Total Rigid Body Mass
APDL Math is used to calculate the participation factors and total rigid body mass based on the database
file (test.db), the full file (test.full), and the mode file (test.mode) from a modal analysis. This
procedure is particularly useful if the effect of boundary conditions and CP/CE is required.
/filname,test
resume,, db
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 53
APDL Math
jobcurrmode(1)=''
*do,i,1,248,8
*get,param,ACTIVE,0,JOBNAME,,START,i
jobcurr(1) = strcat(jobcurr(1),param)
*enddo
jobcurrfull(1) = strcat(jobcurr(1),'.full')
jobcurrmode(1) = strcat(jobcurr(1),'.mode')
*dmat,rig,D,IMPORT,APDL,rig_apdl
*mult,usrtobcs,,rig,,rigbcs
*mult,mass,,rigbcs,,prodr
*dmat,PhiF,,IMPORT,MODE,jobcurrmode(1),1,4
*mult,NodToBcs,,PhiF,,PhiR
*free,PhiF
*mult,PhiR,T,prodr,,pfall
*print,pfall ! participation factors
*mult,rigbcs,T,prodr,,mtot
*print,mtot ! total rigid body mass
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
54 of ANSYS, Inc. and its subsidiaries and affiliates.
Chapter 5: APDL as a Macro Language
You can record a frequently used sequence of Mechanical APDL commands in a macro file (these are
sometimes called command files). Creating a macro enables you to, in effect, create your own custom
Mechanical APDL command. For example, calculating power loss due to eddy currents in a magnetic
analysis would require a series of Mechanical APDL commands in the postprocessor. By recording this
set of commands in a macro, you have a new, single command that executes all of the commands re-
quired for that calculation. In addition to executing a series of Mechanical APDL commands, a macro
can call GUI functions or pass values into arguments.
You can also nest macros. That is, one macro can call a second macro, the second macro can call a third
macro, and so on. You can use up to 20 nesting levels, including any file switches caused by the
Mechanical APDL /INPUT command. After each nested macro executes, the Mechanical APDL program
returns control to the previous macro level.
The following is a very simple example macro file. In this example, the macro creates a block with di-
mensions 4, 3, and, 2 and a sphere with a radius of 1. It then subtracts the sphere from one corner of
the block.
/prep7
/view,,-1,-2,-3
block,,4,,3,,2
sphere,1
vsbv,1,2
finish
If this macro were called mymacro.mac, you could execute this sequence of commands with the fol-
lowing single Mechanical APDL command
*use,mymacro
This chapter provides information on the various ways you can create, store, and execute macros. It
also discusses the basic information you need to use APDL as a scripting language in creating macros.
APDL commands used to define and execute macros are listed in Chapter 2 of the Command Reference.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 55
APDL as a Macro Language
For any long, complex macro you should always consider either using a similar macro as a starting point
or running the task interactively in Mechanical APDL and using the resulting log file as the basis of your
macro. Either method can greatly reduce the time and effort required to create a suitable macro.
• The file extension cannot contain more than eight characters (if you are executing the macro as if it
were a Mechanical APDL command it should have the extension .mac.)
• The file name or extension cannot contain any characters prohibited by your file system and for port-
ability should not contain any characters prohibited by either Linux or Windows file systems.
To ensure that you are not using the name of a Mechanical APDL command, before creating a macro
try running the file name that you wish to use as a Mechanical APDL command. If Mechanical APDL
returns the message shown below, you will know that the command is not used in the current processor.
You should check the macro file name in each processor in which you plan to use the macro. (You
could also check if the macro file name matches any command listed in the online documentation;
however, this method cannot locate the names of undocumented commands.)
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
56 of ANSYS, Inc. and its subsidiaries and affiliates.
Creating a Macro
Using the .mac extension allows Mechanical APDL to execute the macro as it would any internal
command. You should avoid using the extension .MAC because it is used for Mechanical APDL internal
macros.
2. The directory (or directories) designated by the ANSYS_MACROLIB environment variable (if defined)
or the login (home) directory. This environment variable is documented in The Mechanical APDL En-
vironment chapter of the Operations Guide.
You can place macros for your personal use in your home directory. Macros that should be available
across your site should be placed in the /ansys_inc/v182/ansys/apdl directory or some commonly
accessible directory that everyone can reference through the ANSYS_MACROLIB environment variable.
For Windows users: The "current directory" is the default directory (usually a network resource) set by
administrators and you should ask your network administrator for its location. You can use environment
variables to create a local "home directory." The local home directory is checked after the default directory
designated in your domain profile.
• Issue the *CREATE command in the input window. Parameter values are not resolved and parameter
names are written to the file.
• Use the *CFOPEN, *CFWRITE, and *CFCLOS commands. Parameter names are resolved to their current
values and those values are written to the macro file.
• Issue the /TEE command in the input window. This command writes a list of commands to a file at the
same time that the commands are being executed. As the commands are executed in the current
Mechanical APDL session, parameter names are resolved to their current values. However, in the file
that is created, parameter values are not resolved and parameter names are written instead.
• Choose the Utility Menu> Macro> Create Macro menu item. This method opens a dialog box that
can be used as a simple, multiline editor for creating macros. Parameter values are not resolved and
parameter names are written to the file.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 57
APDL as a Macro Language
For example, suppose that you want to create a macro called matprop.mac, which automatically
defines a set of material properties. The set of commands entered into the input window for this macro
might look like this:
*CREATE,matprop,mac,macros
MP,EX,1,2.07E11
MP,NUXY,1,.27
MP,DENS,1,7835
MP,KXX,1,42
*END
The *CREATE command takes arguments of the file name, the file extension, and the directory path
(in this case, the macros directory is specified).
When using *CREATE, all parameters used in commands are written to the file (the currently assigned
values for the parameter are not substituted).
Note that parameters were used for arguments to the BLOCK command. The current value of those
parameters (and not the parameter names) are written to the file. So, for this example, the line written
to the macro file might be
*cfwrite,block,,4,,2.5,,2
Note
While it is possible to create a macro through this method, these commands are most useful
as a method for writing Mechanical APDL commands to a file during macro execution.
In addition to the Label argument (which can have a value of NEW, APPEND, or END), the /TEE com-
mand takes arguments of the file name, the file extension, and the directory path.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
58 of ANSYS, Inc. and its subsidiaries and affiliates.
Creating a Macro
As the commands are executed in the current Mechanical APDL session, all parameter names are resolved
to their current values. However, in the file that is created, parameter names are written (the currently
assigned values for the parameter are not substituted). If your current parameter values are important,
you can save the parameters to a file using the PARSAV command.
For an example, see the description of the /TEE command in the Command Reference.
As with the *CREATE command, parameters are not evaluated but are written verbatim into the macro
file. Note that you do not make the last line a *END command.
If you use this method to create macros, do not include the *CREATE and *END commands.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 59
APDL as a Macro Language
Macros libraries have no explicit file extension and follow the same file naming conventions as macro
files. A macro library file has the following structure:
MACRONAME1
.
.
.
/EOF
MACRONAME2
.
.
.
/EOF
MACRONAME3
.
.
.
./EOF
For example, the following macro file contains two simple macros:
mybloc
/prep7
/view,,-1,-2,-3
block,,4,,3,,2
finish
/EOF
mysphere
/prep7
/view,,-1,-2,-3
sphere,1
finish
/EOF
Note that each macro is prefaced with a macro name (sometimes referred to as a data block name) and
ends with a /EOF command.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
60 of ANSYS, Inc. and its subsidiaries and affiliates.
Executing Macros and Macro Libraries
A macro library file can reside anywhere on your system, although for convenience you should place
it within the macro search path. Unlike macro files, a macro library file can have any extension up to
eight characters.
In this case, the macro takes no arguments. If instead the macro was called MYMACRO.MACRO and
resided in /myaccount/macros, you could call it with
*use,/myaccount/macros/mymacro.macro
Note that the *USE command allows you to enter the path and extension along with the file name and
that these are not entered as separate arguments.
If a macro has a .mac file extension and resides in the search path, you can execute it as if it were a
Mechanical APDL command by simply entering it in the command input window. For example, to call
mymacro.mac you could simply enter
mymacro
You can also execute macros with a .mac extension through the Utility Menu> Macro> Execute Macro
menu item.
If the same macro takes arguments (see Passing Arguments to a Macro (p. 62) for more information
about passing arguments to macros), then these can be entered on the command line as follows
mymacro,4,3,2,1.5
or
*use,mymacro.mac,4,3,2,1.5
The Utility Menu> Macro> Execute Macro menu item dialog provides fields for arguments.
Executing macros contained in macro libraries is similar. You must first specify the library file using the
*ULIB command. For example, to specify that macros are in the mymacros.mlib file, which resides
in the /myaccount/macros directory, you would issue the following command:
*ulib,mymacros,mlib,/myaccount/macros/
After selecting a macro library, you can execute any macro contained in the library by specifying it
through the *USE command. As with macros contained in individual files, you can specify arguments
as parameters in the *USE command.
Note
You cannot use the *USE command to access macros not contained in the specified macro
library file after issuing the *ULIB command.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 61
APDL as a Macro Language
• A set of scalar parameters that provide a way of passing command line arguments to the macro.
• A set of scalar parameters that can be used within the macro. These provide a set of local variables that
can be used to define values only within that macro.
• Numbers
• Parametric expressions
Note
You can pass only the values of parameters ARG1 through AR18 to a macro as arguments
with the *USE command. If you create a macro that can be used as a Mechanical APDL
command (the macro files has a .mac extension), you can pass the values of parameters
ARG1 through AR19 to the macro.
For example, the following simple macro requires four arguments, ARG1, ARG2, ARG3, and ARG4:
/prep7
/view,,-1,-2,-3
block,,arg1,,arg2,,arg3
sphere,arg4
vsbv,1,2
finish
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
62 of ANSYS, Inc. and its subsidiaries and affiliates.
Controlling Program Flow in APDL
• Repeat the execution of a single command, incrementing one or more command parameters.
The following sections detail each of these program control capabilities. For the exact syntax of the
commands, refer to the Command Reference.
5.4.1. Nested Macros: Calling Subroutines Within a Macro
5.4.2. Unconditional Branching: Goto
5.4.3. Conditional Branching: The *IF Command
5.4.4. Repeating a Command
5.4.5. Looping: Do-Loops
5.4.6. Implied (colon) Do Loops
5.4.7. Additional Looping: Do-While
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 63
APDL as a Macro Language
*GO,:BRANCH1
--- ! This block of commands is skipped (not executed)
---
:BRANCH1
---
---
The label specified by the *GO command must start with a colon (:) and must not contain more than
eight characters, including the colon. The label can reside anywhere within the same file.
Note
The use of *GO is now considered obsolete and is discouraged. See the other branching
commands for better methods of controlling program flow.
Where
• VAL1 is the first numerical value (or numerical parameter) in the comparison.
• VAL2 is the second numerical value (or numerical parameter) in the comparison.
APDL offers eight comparison operators, which are discussed in detail in the *IF command reference.
Briefly these are:
EQ
Equal (for VAL1 = VAL2).
NE
Not equal (for VAL1 ≠ VAL2).
LT
Less than (for VAL1 < VAL2).
GT
Greater than (for VAL1 > VAL2).
LE
Less than or equal (for VAL1 VAL2).
GE
Greater than or equal (for VAL1 VAL2).
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
64 of ANSYS, Inc. and its subsidiaries and affiliates.
Controlling Program Flow in APDL
ABLT
Absolute values of VAL1 and VAL2 before < operation.
ABGT
Absolute values of VAL1 and VAL2 before > operation.
By giving the Base argument a value of THEN, the *IF command becomes the beginning of an if-then-
else construct (similar to the FORTRAN equivalent). The construct consists of
In its simplest form, the *IF command evaluates the comparison and, if true, branches to a label specified
in the Base argument. This is similar to the "computed goto" in FORTRAN. (In combination, a set of
such *IF commands could function similarly to the CASE statements in other programming languages.)
Take care not to branch to a label within an if-then-else construct or do-loop. If a batch input stream
hits an end-of-file during a false *IF condition, the Mechanical APDL run will not terminate normally.
You will need to terminate it externally (use either the Linux “kill” function or the Windows task manager).
By setting the Base argument to a value of STOP, you can exit from Mechanical APDL based on a
particular condition.
An if-then-else construct simply evaluates a condition and executes the following block or jumps to
the next statement following the *ENDIF command (shown with the "Continue" comment).
*IF,A,EQ,1,THEN
! Block1
.
.
*ENDIF
! Continue
The following example shows a more complex structure. Note that only one block can be executed. If
no comparison evaluates to true, the block following the *ELSE command is executed.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 65
APDL as a Macro Language
Note
You can issue a /CLEAR command within an if-then-else construct. The /CLEAR command
does not clear the *IF stack and the number of *IF levels is retained. An *ENDIF is necessary
to close any branching logic. Also, keep in mind that the /CLEAR command deletes all
parameters, including any that are used in your branching commands. You can avoid any
problems that might arise from the deletion of parameters by issuing a PARSAV command
before the /CLEAR command, and then following the /CLEAR command with a PARRES
command.
the E command generates one element between nodes 1 and 2 and the following *REPEAT command
specifies that E executes a total of five times (including the original E command), incrementing the
second node number by one for each additional execution. The result is five total elements with node
connectivities 1-2, 1-3, 1-4, 1-5, and 1-6.
Note
Most commands that begin with a slash (/) or an asterisk (*), as well as macros executed as
"unknown commands," cannot be repeated. However, graphics commands that begin with
a slash can be repeated. Also, avoid using the *REPEAT command with interactive commands,
such as those that require picking or those that require a user response.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
66 of ANSYS, Inc. and its subsidiaries and affiliates.
Controlling Program Flow in APDL
The following example do-loop edits five load step files (numbered 1 through 5) and makes the same
changes in each file.
*DO,I,1,5 ! For I = 1 to 5:
LSREAD,I ! Read load step file I
OUTPR,ALL,NONE ! Change output controls
ERESX,NO
LSWRITE,I ! Rewrite load step file I
*ENDDO
You can add your own loop controls by using the *IF, *EXIT, or *CYCLE commands.
• Do not branch out of a do-loop with a :Label on the *IF or *GO commands.
• Avoid using a :Label to branch to a different line within a do-loop. Use if-then-else-endif instead.
• Output from commands within a do-loop is automatically suppressed after the first loop. Use /GOPR
or /GO (no response line) within the do-loop if you need to see output for all loops.
• Take care if you include a /CLEAR command within a do-loop. The /CLEAR command does not clear
the do-loop stack, but it does clear all parameters including the loop parameter in the *DO statement
itself. You can avoid the problem of having an undefined looping value by issuing a PARSAV command
before the /CLEAR command, and then following the /CLEAR command with a PARRES command.
When using the implied (colon) do loops, be aware that the shortest expression controls execution. For
example,
n,(1:7),(2:12:2)
Additional numeric fields that do not have the colon (:) will be taken as a constant value.
Also, non-integer numbers will function normally. However, if non-integer numbers are applied to a
command that requires integers, then the non-integer will be rounded off following normal mathemat-
ical conventions.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 67
APDL as a Macro Language
This looping convention can be used only for fields requiring a numeric entry. Looping may also be
used with GET function arguments, for example a(1:5)=nx(1:5). A text entry field will process (x:y:z) as
a literal value.
*DOWHILE,Parm
The loop repeats as long as the parameter Parm is TRUE. If Parm becomes false (less than or equal to
0.0), the loop terminates. The *CYCLE and *EXIT commands can be used within a *DOWHILE loop.
Most of the important information about these commands appears here, but you may want to look at
the complete command descriptions in the Command Reference.
*ENDDO Ends a "do" loop and You must use one *ENDDO command for each nested "do"
starts the looping loop. The *ENDDO and *DO commands for a loop must be
action. on the same file.
*CYCLE When executing a You can use the cycle option conditionally (via the *IF
"do" loop, Mechanical command). The *CYCLE command must appear on the same
APDL bypasses all file as the *DO command and must appear before the *ENDDO
commands between command.
the *CYCLE and
*ENDDO commands,
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
68 of ANSYS, Inc. and its subsidiaries and affiliates.
Using the _STATUS and _RETURN Parameters in Macros
*ENDIF Terminates an The *IF and *ENDIF commands must appear in the same file.
if-then-else construct.
(See the *IF
discussion for details.)
*ELSE Creates a final, The *ELSE and *IF commands must appear in the same file.
optional block
separator within an
if-then-else construct.
(See the *IF
discussion for details.)
*ELSEIF Creates an optional, If Oper = EQ or NE, VAL1 and VAL2 can also be character
intermediate block strings (enclosed in quotes) or parameters. The *IF and *ELSEIF
separator within an commands must be on the same file.
if-then-else construct.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 69
APDL as a Macro Language
Solid modeling functions generate the _RETURN parameter, which contains the result of executing the
function. The following table defines the _RETURN values for the various solid modeling functions:
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
70 of ANSYS, Inc. and its subsidiaries and affiliates.
Reviewing Example Macros
Executing a Mechanical APDL command, whether in a macro or elsewhere, generates the parameter
_STATUS. This parameter reflects the error status of that command:
• 0 for no error
• 1 for a note
• 2 for a warning
• 3 for an error
You can also create assemblies, which are groups that combine two or more components or even
multiple assemblies. You can nest assemblies up to five levels deep. For example, you could build an
assembly named motor from components called STATOR, PERMMAG, ROTOR, and WINDINGS.
The table below describes some of the commands you can issue to build components and assemblies.
For more detailed discussions of these commands, see the Command Reference. For further information
on components and assemblies, see Selecting and Components in the Basic Analysis Guide.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 71
APDL as a Macro Language
The following example macro, called bilinear.mac, evaluates two bilinear materials. This is a useful
macro that can be run after solving a static analysis. Material 1 is the tension properties, and Material
2 is the compression properties. ARG1 is the number of iterations (default is 2).
/nop
_niter = arg1 ! set number of iterations
*if,_niter,lt,2,then
_Niter = 2
*endif
*do,iter,1,_niter ! loop on number of iterations
/post1
set,1,1
*get,ar11,elem,,num,maxd ! Get number of elements
*dim,_s1,,ar11 ! array for element s1
*dim,_s3,,ar11 ! array for element s3
etable,sigmax,s,1 ! s1 is in element table sigmax
etable,sigmin,s,3 ! s3 is in element table sigmin
*vget,_s1(1),elem,1,etab,sigmax ! get element maximum stress in s1
*vget,_s3(1),elem,1,etab,sigmin ! get element minimum stress in s3
*dim,_mask,,ar11 ! array for mask vector
*voper,_mask(1),_s1(1),lt,0 ! true if max. stress < 0
*vcum,1 ! accumulate compression elements
*vabs,0,1 ! absolute value of s3
*voper,_mask(1),_s3(1),gt,_s1(1) ! true if abs(minstr) > maxstr
finish
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
72 of ANSYS, Inc. and its subsidiaries and affiliates.
Reviewing Example Macros
emod,all
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 73
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
74 of ANSYS, Inc. and its subsidiaries and affiliates.
Chapter 6: Interfacing with the GUI
Within a Mechanical APDL macro, you have several ways to access components of the Mechanical APDL
graphical user interface (GUI):
• You can modify and update the Mechanical APDL toolbar (discussed in Adding Commands to the
Toolbar).
• You can issue the *ASK command to prompt a user to enter a single parameter value.
• You can create a dialog box to prompt a user to enter multiple parameter values.
• You can issue the *MSG command to have the macro write an output message.
• You can allow the user to select entities through graphical picking from within a macro.
*ASK,Par,Query,DVAL
Where
• Par is an alphanumeric name that identifies the scalar parameter used to store the user input.
• Query is the text string that Mechanical APDL displays to prompt the user. This string can contain up
to 54 characters. Don't use characters that have special meanings, such as "$" or "!".
• DVAL is the default value given the parameter if a user issues a blank response. This value can be either
a one-to-eight character string (enclosed in single quotes) or a number. If you assign no default, a blank
user response deletes the parameter.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 75
Interfacing with the GUI
The *ASK command prints the Query text on the screen and waits for a response. It reads the response
from the keyboard except when Mechanical APDL runs in batch mode. (In that case, the response or
responses must be the next-read input line or lines.) The response can be a number, a one-to-eight
character string enclosed in single quotes, a numeric or character parameter, or an expression that
evaluates to a number. Mechanical APDL then sets the value of Par to the read-in response. The fol-
lowing example displays the dialog box shown below, then sets the parameter PARM1 to the value the
user enters.
*ask,parm1,'username (enclose the username in single quotes)'
When you issue *ASK within a macro, Mechanical APDL writes the user's response to File.LOG on
the line following the macro name.
• Up to two special *CSET commands that provide a two line area for user instructions.
Where
'start'
A literal string that, when encountered as the first argument, marks the beginning of the MULTIPRO
construct. The literal must be enclosed in single quotes.
Prompt_Num
Required only if Def_Value is omitted from at least one *CSET command or if Def_Value is
set to 0. The Prompt_Num value is an integer equal to the number of following *CSET prompts.
Strt_Loc,End_Loc
The initial value for Strt_Loc for the first *CSET command is 1, and the value for End_Loc is
Strt_Loc+2 (3 for the first *CSET command). The value of each subsequent Strt_Loc is the pre-
vious End_Loc+1.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
76 of ANSYS, Inc. and its subsidiaries and affiliates.
Prompting Users With a Dialog Box
Param_Name
The name of the parameter that will hold either the value specified by the user or, if the user supplies
no value, the value of Def_Value .
''Prompt_String''
A string, which can contain up to 32 characters, which can be used to describe the parameter. This
string must be enclosed in single quotes.
Def_Value
Default value used if no value specified by user. Default value can be a numeric expression including
APDL numeric parameters. Character expressions are not allowed.
'end'
A literal string, used as the first argument for the closing MULTIPRO command.
Up to two optional *CSET commands can be added to the construct that can provide two 64 character
strings. You can use these to provide instructions to the user. The syntax for these specialized *CSET
commands is
*CSET,61,62,'Help_String','Help_String'*CSET,63,64,'Help_String','Help_String'
Where
'Help_String'
A string which can contain up to 32 characters. If you need more than 32 characters, you can use a
second Help_String argument.
The following is an example of a MULTIPRO construct using the optional help lines. Note that two
Help_String arguments are used to overcome the 32 character limit.
multipro,'start',3
*cset,1,3,dx,'Enter DX Value',0.0
*cset,4,6,dy,'Enter DY Value',0.0
*cset,7,9,dz,'Enter DZ Value',0.0
*cset,61,62,'The MYOFSET macro offsets the',' selected nodes along each'
*cset,63,64,'of the three axes. Fill in the ',' fields accordingly.'
multipro,'end'
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 77
Interfacing with the GUI
You can check the status of the buttons by testing the value of the _BUTTON parameter. The following
lists the button status values:
Where Lab is one of the following labels for output and termination control:
VAL1 through VAL8 are numeric or alphanumeric character values to be included in the message. Values
can be the results of evaluating parameters. All numeric values are assumed to be double precision.
You must specify the message format immediately after the *MSG command. The message format can
contain up to 80 characters, consisting of text strings and predefined "data descriptors" between the
strings where numeric or alphanumeric character data are to be inserted. These data descriptors are:
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
78 of ANSYS, Inc. and its subsidiaries and affiliates.
Creating and Maintaining a Status Bar from a Macro
• %i, for integer data. The FORTRAN nearest integer (NINT) function is used to form integers for the %I
descriptor.
The corresponding FORTRAN data descriptors for the first three descriptors are I9, 1PG16.9, and A8 re-
spectively. A blank must precede each descriptor. You also must supply one data descriptor for each
specified value (eight maximum), in the order of the specified values.
Don't begin *MSG format lines with *IF, *ENDIF, *ELSE, or *ELSEIF. If the last non-blank character of
the message format is an ampersand (&), the Mechanical APDL program reads a second line as a con-
tinuation of the format. You can use up to 10 lines (including the first) to specify the format information.
Consecutive blanks are condensed into one blank upon output, and a period is appended. The output
produced can be up to 10 lines of 72 characters each (using the %/ descriptor).
The example below shows you an example of using *MSG that prints a message with two integer values
and one real value:
*MSG, INFO, 4Inner4 ,25,1.2,148
Radius ( %C) = %I, Thick = %G, Length = %I
Note
The command /UIS,MSGPOP controls which messages a message dialog box displays when
the GUI is active. See the Command Reference for more information about this command.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 79
Interfacing with the GUI
• Title40 is the text string that appears in the dialog box with the status bar. The string can contain a maximum
of 40 characters.
• Percent is an integer between 0 and 100. It gives the position of the status bar.
• NewTitle is a 40-character string that contains progress information. If you specify a string for New-
Title, it replaces the string supplied in Title40.
If you specify KILL or BOTH, your macro should check the _RETURN parameter after each execution of
*ABCHECK to see if the user has pressed the STOP button, then take the appropriate action.
To remove the status bar from the Mechanical APDL GUI, issue the *ABFINI command.
The following example macro illustrates the status bar (complete with bar and STOP button) in use.
The status dialog box that is produced is shown in the following figure. Note that the macro checks
the status of the _RETURN parameter and, if the STOP button is pressed, posts the "We are stopped......"
message.
fini
/clear,nost
/prep7
n,1,1
n,1000,1000
fill
*abset,'This is a Status Bar',BOTH
myparam = 0
*do,i,1,20
j = 5*i
*abcheck,j
*if,_return,gt,0,then
myparam = 1
*endif
*if,myparam,gt,0,exit
/ang,,j
nplot,1
*if,_return,gt,0,then
myparam = 1
*endif
*if,myparam,gt,0,exit
nlist,all
*if,_return,gt,0,then
myparam = 1
*endif
*if,myparam,gt,0,exit
*enddo
*if,myparam,gt,0,then
*msg,ui
We are stopped.........
*endif
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
80 of ANSYS, Inc. and its subsidiaries and affiliates.
Calling Dialog Boxes From a Macro
*abfinish
fini
Note
Keep in mind that picking commands are not available in all Mechanical APDL processors, and that you
must first switch to an appropriate processor before calling the command.
Note
If a macro includes GUI functions, the /PMACRO command should be the first command in
that macro. This command causes the macro contents to be written to the session log file.
This is important, because if you omit the /PMACRO command, Mechanical APDL can't read
the session log file to reproduce the Mechanical APDL session.
Keep in mind that many dialog boxes have a number of dependencies, including that the appropriate
Mechanical APDL processor is active and that certain required preexisting conditions are met. For example,
launching a dialog box to select nodes first supposes that nodes exist, if no nodes exist the macro will
fail when the user clicks OK or Apply.
Note
If a macro includes GUI functions, the /PMACRO command should be the first command in
that macro. This command causes the macro contents to be written to the session log file.
This is important, because if you omit the /PMACRO command, Mechanical APDL can't read
the session log file to reproduce the Mechanical APDL session.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 81
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
82 of ANSYS, Inc. and its subsidiaries and affiliates.
Chapter 7: Encrypting Macros
Mechanical APDL provides the ability to encrypt macro files so that the source is not "human-readable."
Encrypted macros require an encryption key to run. You can either place the encryption key explicitly
(in readable ASCII) in the macro or you can set it in Mechanical APDL as a global encryption key.
Encrypted macros are not supported by distributed-memory parallel processing (Distributed ANSYS).
/ENCRYPT,Encryption_key,File_name,File_ext,Directory_Path/
Where
• File_ext is an optional file extension for the encrypted macro file. If you want users to execute the
macro as an "unknown" command, you should use the .mac extension.
• Directory_Path/ is the optional directory path that can contain up to 60 characters; you only need
this argument if you do not want to write the encrypted macro file to your "home" directory.
Note the placement of the /ENCRYPT commands at the top and bottom of the listing in the following
example:
/encrypt,mypasswd,myenfile,mac,macros/
/nopr
/prep7
/view,,-1,-2,-3
block,,arg1,,arg2,,arg3
sphere,arg4
vsbv,1,2
/gopr
finish
/encrypt
The /ENCRYPT command at the top of the macro instructs Mechanical APDL to encrypt the file and
use the string "mypasswd" as the encryption key. It will create an encrypted macro file called myen-
file.mac and place it in the /macros subdirectory of the home directory. The /ENCRYPT command
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 83
Encrypting Macros
at the bottom instructs Mechanical APDL to stop the encryption process and write the encrypted macro
to the specified file.
Note
The encrypted macro uses a /NOPR command as its second line to turn off echoing of
Mechanical APDL commands to the session log file. This is important if you wish to prevent
users from reading the contents of the macro from the session log. It's a good practice to
reactivate the session log by issuing the /GOPR command as the last command in the macro
before the ending /ENCRYPT command.
Note that the individual commands within the macro are now encrypted, and that the encrypted ma-
terial is enclosed by /DECRYPT commands. The encryption key is the argument to the first /DECRYPT
command.
Before executing the macro within Mechanical APDL, issue the following command through the
Mechanical APDL Input command line:
/DECRYPT,PASSWORD,Encryption_Key
Where Encryption_Key is the encryption key used to encrypt the file. You can now execute the
encrypted password. To delete the current global encryption key, issue the following Mechanical APDL
command:
/DECRYPT,PASSWORD,OFF
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
84 of ANSYS, Inc. and its subsidiaries and affiliates.
Chapter 8: APDL Commands
*ABBR
ABBRES
ABBSAV
*AFUN
*ASK
*AXPY
*CFCLOS
*CFOPEN
*CFWRITE
*COMP
*CREATE
*CYCLE
*DEL
/DFLAB
*DIM
/DIRECTORY
*DMAT
*DO
*DOWHILE
*EIGEN
*ELSE
*ELSEIF
*END
*ENDDO
*ENDIF
*EXIT
*EXPORT
*FREE
*GET
*GO
*IF
/INQUIRE
*ITENGINE
*LSBAC
*LSENGINE
*LSFACTOR
/MAIL
*MFOURI
*MFUN
/MKDIR
*MOPER
*MSG
*MULT
*MWRITE
*NRM
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 85
APDL Commands
PARRES
PARSAV
/PMACRO
*PRINT
/PSEARCH
*REPEAT
*RETURN
/RMDIR
*SET
*SMAT
*SREAD
*STATUS
*TAXIS
/TEE
*TOPER
*TREAD
/UCMD
*ULIB
*USE
*VABS
*VCOL
*VCUM
*VEC
*VEDIT
*VFACT
*VFILL
*VFUN
*VGET
*VITRP
*VLEN
*VMASK
*VOPER
*VPLOT
*VPUT
*VREAD
*VSCFUN
*VSTAT
*VWRITE
/WAIT
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
86 of ANSYS, Inc. and its subsidiaries and affiliates.
Appendix A. GET Function Summary
A "get function" is available for some items and can be used instead of the *GET command. The function
returns the value and uses it where the function is input, bypassing the need for storing the value with
a parameter name and inputting the parameter name where the value is to be used.
For example, assume the average X location of two nodes is to be calculated. Using the *GET command,
parameter L1 can be assigned the X location of node 1, and parameter L2 can be assigned the X location
of node 2. Then the mid-location can be computed from MID = (L1 + L2) / 2:
*GET,L1,NODE,1,LOC,X
*GET,L2,NODE,2,LOC,X
MID=(L1+L2)/2
However, using the node location "get function" NX(N), which returns the X location of node N, MID
can be computed directly without the need for intermediate parameters L1 and L2:
MID=(NX(1)+NX(2))/2
Get functions return values in the active coordinate system unless stated otherwise.
Get function arguments may themselves be parameters or other get functions. The get function
NELEM(E,NPOS) returns the node number in position NPOS for element number E. Combining functions,
NX(NELEM(E,NPOS)) returns the X location of that node.
The table below lists available get functions grouped by functionality. The *GET command also lists
get functions as alternatives to *GET items, where applicable (see the tables in the Notes section of
*GET).
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 87
GET Function Summary
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
88 of ANSYS, Inc. and its subsidiaries and affiliates.
"Get Function" Summary
Entity Status Get Function Description
DISTEN(E,N) Distance between the centroid of element E and node N.
Centroid is determined from the selected nodes on the
element.
Angles (in radians by default -- see the *AFUN command)
ANGLEN(N1,N2,N3) Subtended angle between two lines (defined by three nodes
where N1 is the vertex node). Default is in radians.
ANGLEK(K1,K2,K3) Subtended angle between two lines (defined by three
keypoints where K1 is the vertex keypoint). Default is in
radians.
Nearest to Entity
NNEAR(N) Selected node nearest node N.
KNEAR(K) Selected keypoint nearest keypoint K.
ENEARN(N) Selected element nearest node N. The element position is
calculated from the selected nodes.
Areas
AREAND(N1,N2,N3) Area of the triangle with vertices at nodes N1, N2, and N3.
AREAKP(K1,K2,K3) Area of the triangle with vertices at keypoints K1, K2, and
K3.
ARNODE(N) Area at node N apportioned from selected elements attached
to node N. For 2-D planar solids, returns edge area associated
with the node. For axisymmetric solids, returns edge surface
area associated with the node. For 3-D volumetric solids,
returns face area associated with the node. For 3–D, select
all the nodes of the surface of interest before using ARNODE.
Normals
NORMNX(N1,N2,N3) X-direction cosine of the normal to the plane containing
nodes N1, N2, and N3.
NORMNY(N1,N2,N3) Y-direction cosine of the normal to the plane containing
nodes N1, N2, and N3.
NORMNZ(N1,N2,N3) Z-direction cosine of the normal to the plane containing
nodes N1, N2, and N3.
NORMKX(K1,K2,K3) X-direction cosine of the normal to the plane containing
keypoints K1, K2, and K3.
NORMKY(K1,K2,K3) Y-direction cosine of the normal to the plane containing
keypoints K1, K2, and K3.
NORMKZ(K1,K2,K3) Z-direction cosine of the normal to the plane containing
keypoints K1, K2, and K3.
Connectivity
ENEXTN(N,LOC) Element connected to node N. LOC is the position in the
resulting list when many elements share the node. A zero
is returned at the end of the list.
NELEM(E,NPOS) Node number in position NPOS (1--20) of element E.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 89
GET Function Summary
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
90 of ANSYS, Inc. and its subsidiaries and affiliates.
"Get Function" Summary
Entity Status Get Function Description
ROTY(N) ROTY structural rotation at node N.
ROTZ(N) ROTZ structural rotation at node N.
TEMP(N) Temperature at node N. For SHELL131 and SHELL132
elements with KEYOPT(3) = 0 or 1, use TBOT(N), TE2(N),
TE3(N), . . ., TTOP(N) instead of TEMP(N).
PRES(N) Pressure at node N.
VX(N) VX fluid velocity at node N.
VY(N) VY fluid velocity at node N.
VZ(N) VZ fluid velocity at node N.
VOLT(N) Electric potential at node N.
MAG(N) Magnetic scalar potential at node N.
AZ(N) AZ magnetic vector potential at node N.
Returns information about the database manager
VIRTINQR(1) Number of pages in core.
VIRTINQR(4) Page size in integer words.
VIRTINQR(7) Maximum number of pages allowed on disk.
VIRTINQR(8) Number of read/write operations on page.
VIRTINQR(9) Maximum record number on page.
VIRTINQR(11) Maximum pages touched.
Returns the current value of Mechanical APDL filtering keywords.
KWGET(KEYWORD) Returns the current value the keyword specified by
KEYWORD. See the UIDL Programmer's Guide for a list of
keywords and values.
Character String Functions Strings must be dimensioned (see *DIM) as a character parameter
or enclosed in single apostrophes ('char').
Functions which return a double precision value of a numeric character string.
VALCHR(a8) a8 is a decimal value expressed in a string.
VALOCT (a8) a8 is an octal value expressed in a string.
VALHEX(a8) a8 is a hex value expressed in a string.
Functions which return an 8 character string of a numeric value.
CHRVAL (dp) dp is a double precision variable.
CHROCT (dp) dp is an integer value.
CHRHEX(dp) dp is an integer value.
Functions which manipulate strings: StrOut is the output string (or character parameter) Str1 and
Str2 are input strings. Strings are a maximum of 128 characters. (see *DIM)
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 = STRFILL(Str1,Str2,nLoc) Add Str2 to Str1 starting at character nLoc.
StrOut = STRCOMP(Str1) Remove all blanks from Str1
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 91
GET Function Summary
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
92 of ANSYS, Inc. and its subsidiaries and affiliates.
Appendix B. Using APDL to List File Structure and Content
The *XPL command enables you to explore the contents of a Mechanical APDL file. Use this command
to traverse up and down the tree structure of the specified file and review what is in the file. Files that
can be scanned include .RST, .MODE, .FULL, .CMS, and .SUB files.
Action
Specifies the action for scanning file content (no default). Valid labels are:
Val1, Val2
Additional input. The meanings of Val1 and Val2 vary depending on the specified Action, as described
in the table below.
The command *XPL,READ generates either a *VEC or a *DMAT object according to the record type.
You do not have to create the APDL Math object before issuing this command.
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 93
Using APDL to List File Structure and Content
Not all records can be addressed by the *XPL command. You can only access those records listed by
the Action = LIST option.
Following is an example input listing that demonstrates use of the *XPL command.
You must open a file (Action = OPEN) in order to scan it. For example, you can open an .RST file
and list the records (Action = LIST).
*XPL,OPEN,file.rst,RST
===============================================
===== ANSYS File Xplorer ======
===============================================
BEGIN:
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
94 of ANSYS, Inc. and its subsidiaries and affiliates.
Using the *XPL Command
*XPL,LIST
===== ANSYS File Xplorer : List Blocks in File file.rst
A record name ending in “::HEADER” indicates a header. The record sizes are listed for each record. The
“Total Size” value is the sum of the sizes of all the records addressed (recursively) by the corresponding
header.
In this example the STEP option is used to go down one level under the GEO header:
*XPL,STEP,GEO
===== ANSYS File Xplorer : Step into Block GEO
BEGIN:
*XPL,LIST
===== ANSYS File Xplorer : List Blocks in File apdl-196s.rst
The WHERE option displays the current location in the tree of records:
*XPL,WHERE
===== ANSYS File Xplorer : Display Current Location
The READ option reads a record and fills an APDL Math vector:
*XPL,READ,ETY,MyVec
===== ANSYS File Xplorer : Read Block ETY into the Vector MYVEC
*PRINT,MyVec
MYVEC :
Size : 7
10 213 416 619 822
1025 1228
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 95
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
96 of ANSYS, Inc. and its subsidiaries and affiliates.
matrix operations, 37
Index operations, 34
plotting, 42
Symbols specifying values, 23
*XPL command, 93 TABLE, 18, 21
examples, 21
writing data files, 32
A Array parameters
*ABBR command, 3, 16
ARRAY
*ABBRES command, 5
examples, 21
abbreviations
*ASK command, 14
defined, 3
defined, 75
files, 5
nesting on toolbar, 5
*ABBSAV command, 5
C
*ABCHECK command *CFCLOS command, 58
defined, 79 *CFOPEN command, 32, 58
*ABFINI command, 79 *CFWRITE command, 14, 58
*AFUN command, 17 CHAR
ANSYS_MACROLIB environment variable, 57 defined, 18
APDL examples, 21
comments, 16 limitation with *VEDIT, 25
defined, 1 naming conflict, 23
macros, 55 character parameters, 12
mathematical functions, 17 comment character, 16
operators, 16 *CREATE command, 57
APDL Math, 45 create macro dialog box, 59
degree-of-freedom ordering, 48 *CSET command, 76
examples, 50 *CYCLE command, 66
matrix and vector sizes, 47 defined, 68
procedure, 46
AR20 through AR99, 62 D
ARG1 through AR19, 62 data descriptors, 14, 33
ARRAY in messages, 78
defined, 18 data files
examples, 21 writing from arrays, 32
array parameters, 18 /DECRYPT command, 84
1-D table example, 26 macros
2-D table example, 26 introduction to programming, 55
3-D table example, 26 *DIM command, 15, 22-23
ARRAY, 18 *DO command, 66
basics, 19 defined, 68
CHAR, 18 do-loops, 66
examples, 21 vector operations, 34
naming conflict, 23 do-while, 68
defining, 22
editing interactively, 25 E
examples, 21 *ELSE command, 64, 78
filling from a data file, 26 defined, 68
filling vectors, 25 *ELSEIF command, 14, 64, 78
interpolating values, 30 defined, 68
labeling, 43 /ENCRYPT command
listing, 22, 31 defined, 83
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 97
Index
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
98 of ANSYS, Inc. and its subsidiaries and affiliates.
assigning through Mechanical APDL command line, defined, 18
9 examples, 21
assigning through Mechanical APDL Launcher, 9 /TEE command, 58
character, 12, 15 text editor, 59
defining, 9 /TITLE command, 14, 16
deleting, 12 /TLABEL command, 14, 16
dynamic substitution of, 16 toolbar
forcing substitution of, 14 default buttons, 3
listing, 11 modifying, 3
maximum number, 11 nesting abbreviations on, 5
PASSWORD, 84 *TREAD command, 23, 26
preventing substitution of, 13
resuming, 18 U
saving, 18 UIDL functions
substituting numeric values, 13 calling in macros, 81
using *GET, 10 /UIS command, 78
using get functions, 10 *ULIB command, 61
using in-line get functions, 11 unknown command
writing, 18 method for executing macros, 61
Parameters *USE command, 61
naming conventions, 8
parametric expressions, 16 V
parametric functions, 17 *VABS command, 39
PARRES command, 14, 18 *VCOL command, 39
PARSAV command, 14, 18 *VCUM command, 39
passing arguments to macros, 62 vector operations, 34
plotting *VEDIT command, 15, 23
array vectors, 42 defined, 25
labeling, 43 *VFACT command, 39
/PMACRO command, 81 example, 39
*VFILL command, 15, 23, 34
R defined, 25
*REPEAT command, 66 example, 39
repeating a command, 66 *VFUN command, 15, 34
RESUME command, 14 examples, 34, 39
parameters *VGET command, 15, 34
retrieving or restoring parameter values, 31 *VITRP command, 15, 34
*VLEN command, 15, 39
S examples, 39
*SET command, 9, 15, 23 *VMASK command, 15, 39
specification commands example, 39
vector and matrix operations, 39 *VOPER command, 15, 34
start.ans file, 9 examples, 34
status bar, 79 gather and scatter, 34
*STATUS command, 11, 15, 31, 39 *VPLOT command
examples, 31 defined, 42
/STITLE command, 14, 16 defining curve labels, 43
STOP button examples, 42
creating using a macro, 79 *VPUT command
defined, 31
T *VREAD command, 14-15, 23, 26, 34, 39
TABLE *VSCFUN command, 15, 34
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 99
Index
*VSTAT command, 39
*VWRITE command, 14-15, 18, 34, 39
data descriptors, 33
example, 33
W
windows
current directory, 57
Release 18.2 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
100 of ANSYS, Inc. and its subsidiaries and affiliates.