Using Parameters in ANSYS
Using Parameters in ANSYS
3.1 Parameters
Parameters are APDL variables (they are more similar to Fortran variables than to Fortran parameters). You
don't need 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.
ANSYS uses two types of parameters: scalar and array. The first part of this chapter discusses information
that is applicable to both types. Starting with section 3.11, the information is specific to array type
parameters.
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, 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 ANSYS
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
N,12,2.7,4
Valid:
ABC
PI
X_OR_Y
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 1/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
Invalid:
Avoid parameter names that match commonly used ANSYS labels, such as:
Degree of freedom (DOF) labels (TEMP, UX, PRES, etc.)
Convenience labels (ALL, PICK, STAT, etc.)
User-defined labels (such as those defined with the ETABLE command)
Array type field labels (such as CHAR, ARRAY, TABLE, etc.)
Be aware that parameter names ARG1 through ARG9 and AR10 through AR99 are reserved for local
parameters. Generally, local parameters are used in macros (see Section 4.4). Use of these names as
"regular" parameters is not recommended.
Make sure that parameter names don't match abbreviations defined with the *ABBR command. For
more information about abbreviations, see Section 2.1.
Don't begin parameter names with an underscore (_). This is the convention reserved for parameters
used by the GUI and ANSYS-supplied macros.
This capability was added specifically for those who are developing APDL macros for large audiences. You
can use this to build macros that your ANSYS users and other macro programmers cannot list.
You can either assign values to parameters or retrieve values supplied by ANSYS and store these values in
parameters. For retrieving values from ANSYS, you can use either the *GET command or the various inline
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 parameter 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:
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 2/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
ABC=-24
QR=2.07E11
XORY=ABC
CPARM='CASE1'
In the GUI, you can either type the "=" directly in the ANSYS input window or in the "Selection" field of the
Scalar Parameter dialog box (accessed by the Utility Menu>Parameters>Scalar Parameters menu item).
It's a good practice to avoid assigning one or two character parameter names at startup to avoid conflicts with
ANSYS command line options.
Note-Remember that UNIX shells treat single quotes and many other non- alphanumeric characters as
special symbols. When defining character parameters, you must tell UNIX not to interpret the quotes by
inserting a back slash (\) before the single quotes. For example, the following defines two character
parameters having the values `filename' and `200.'
ansys55 -cparm1 \'filename\' -cparm2 \'200\'
If you use the ANSYS Launcher to start ANSYS, you can define parameters through the Interactive or
Batch menu items (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 start5x.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 inline get functions, which can be used in operations. Each get function returns a specific value
from a specific item.
The *GET command (Utility Menu>Parameters>Get Scalar Data) retrieves an ANSYS-supplied value
for an item (a node, an element, an area, etc.) and stores it as a user-named parameter. Various keyword,
label, and number combinations identify the retrieved item. For example, *GET,A,ELEM,5,CENT,X returns
the centroid x-location of element 5 and stores the result as parameter A.
where
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 will be
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 ANSYS Commands Reference.)
You can think of the *GET command as a path down a tree structure, from general to specific information.
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:
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.
Entity Status:
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 4/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
Locations:
Nearest to Location:
Number of the selected node nearest the X,Y,Z point (in the active coordinate system; lowest
NODE(X,Y,Z)
number for coincident nodes)
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 5/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
KP(X,Y,Z) Number of the selected keypoint nearest the X,Y,Z point (in the active coordinate system;
lowest number for coincident keypoints)
Distance:
Distance between the centroid of element E and node N. Centroid is determined from the
DISTEN(E,N)
selected nodes on the element.
Angles:
Subtended angle between two lines (defined by three nodes where N1 is the vertex
ANGLEN(N1,N2,N3)
node). Default is in radians (see the *AFUN command to select degrees).
Subtended angle between two lines (defined by three keypoints where K1 is the
ANGLEK(K1,K2,K3)
vertex keypoint). Default is in radians (see the *AFUN command to select degrees).
Nearest to Entity:
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
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,
ARNODE(N)
returns edge surface area associated with the node. For 3-D volumetric solids,
returns face area associated with the node.
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
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 6/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
NORMKZ(K1,K2,K3) Z-direction cosine of the normal to the plane containing keypoints K1, K2, and K3
Connectivity:
Element connected to node N. LOC is the position in the resulting list when many
ENEXTN(N,LOC)
elements share the node. A zero is returned at the end of the list.
Faces:
Element adjacent to a face (FACE) of element E. The face number is the same as
the surface load key number. Only elements of the same dimensionality and
ELADJ(E,FACE)
shape are considered. A -1 is returned if more than one element is adjacent; A 0
is returned if there are no adjacent elements.
Node in position LOC of a face number FACE of element E. The face number is
NDFACE(E,FACE,LOC) the same as the surface load key number. LOC is the nodal position on the face
(for an IJLK face, LOC=1 is at node I, 2 is at node J, etc.).
Face number of element E containing the selected nodes. The face number output
NMFACE(E) is the surface load key. If multiple load keys occur on a face (such as for line and
area elements), the lowest load key for that face is output.
For 2-D planar solids and 3-D volumetric solids, returns the area of the face of
ARFACE(E) element E containing the selected nodes. For axisymmetric elements, the area is
the full (360°) area.
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 7/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
You can also access this information through either the Utility Menu>List>Other>Parameters or Utility
Menu>List>Status>Parameters>All Parameters menu items.
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 through the Utility Menu>List>Other>Named
Parameter or Utility Menu>List>Status> Parameters>Named Parameters menu items.
Note-Although ANSYS allows a maximum of 1000 parameters, fewer than 1000 are available to the user due
to GUI and ANSYS macro requirements. The number of parameters defined by the user interface (internal
parameters) is listed by the *STATUS command. The command *GET,par,PARM,,MAX returns the total
number of parameters defined.
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 (Utility Menu>Parameters>Scalar Parameters), but don't 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 doesn't delete it. Similarly, setting a character parameter equal to
empty single quotes (` `) or placing blanks within single quotes doesn't delete the parameter.
As arguments to any applicable command field (that is, where alphanumeric input is expected)
As macro name arguments for the *USE command (Utility Menu>Macro>Execute Data Block)
NAME='MACRO' ! MACRO is the name of a macro file
*USE,NAME ! Calls MACRO
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 Section 3.6.2.1 for more
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 9/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
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,
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.
As with numerical parameters, you can force the substitution of a character parameter value in certain cases
where substitution would not occur otherwise. This is done by enclosing the character parameter name with
percent signs (%). Forced substitution of character parameters is valid for the following commands:
/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.)
/TLABEL command (Text field). Specifies text string for annotation.
/SYP command (ARG1 - ARG8 fields). Passes a command string (plus arguments) to the operating
system. (You cannot access the /SYP command directly in the GUI.)
*ABBR command (Abbr field). Defines an abbreviation.
Any filename or extension command argument. These arguments apply to commands such as
/FILENAME, RESUME, /INPUT, /OUTPUT, and FILE. (Direct parameter substitution is also
valid in these fields.)
Any 32 character field: A typical example is the directory path field that is available for many
commands. (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='/ANSYS'
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 10/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
D='/MODELS/'
/STITLE,,RESULTS FROM FILE %C%%D%%A%%B%
SUBTITLE 1 =
RESULTS FROM FILE /ANSYS/MODELS/TEST.RST
/POST1
FILE,A,RST,%C%%D% ! Read results from /ANSYS/MODELS/TEST.RST
*ASK
This command may prompt the user 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.)
*CFWRITE
This command writes ANSYS 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.)
Character parameters may be used for the VAL1 and VAL2 arguments of these commands. For the Oper
argument, only labels EQ (equal) and NE (not equal) are valid when using character parameters. (You
cannot access the *IF and *ELSEIF commands directly in the GUI.) Example:
CPARM='NO'
*IF,CPARM,NE,'YES',THEN
*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.)
These commands will save character parameters to a file (PARSAV command or menu path Utility
Menu>Parameters> Save Parameters) and resume character parameters from a file (PARRES or
Utility Menu>Parameters> Restore Parameters).
*VREAD
This command (Utility Menu>Parameters>Array Parameters>Read from File) can be used to read
alphanumeric character data from a file and produce a character array parameter. The FORTRAN
character descriptor (A) may be used in the format line which must follow the *VREAD command.
*VWRITE
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 11/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
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
applicable only to the *VWRITE and *VREAD commands.
Character parameters are not valid in parametric expressions which use addition, subtraction,
multiplication, etc.
Example:
XYZ='CASE 1'
/TITLE,This is %XYZ%
APLOT
The title "This is CASE 1" will appear on the area plot.
You can then change the value of XYZ and the new title will appear on subsequent plots, even though you
did not reissue /TITLE.
XYZ='CASE 2'
X=A+B
P=(R2+R1)/2
D=-B+(E**2)-(4*A*C) ! Evaluates to D = -B + E2 - 4AC
XYZ=(A<B)+Y**2 ! Evaluates to XYZ = A + Y2 if A is less than B;
! otherwise to XYZ = B + Y2
INC=A1+(31.4/9)
M=((X2-X1)**2-(Y2-Y1)**2)/2
Operator Operation
+ Addition
_ Subtraction
* Multiplication
/ Division
** Exponentiation
You can also use parentheses for clarity and for "nesting" of operations, as shown above. The order in which
the ANSYS program evaluates an expression is as follows:
Thus an expression such as Y2=A+B**C/D*E will be 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 parentheses. 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 *) will be interpreted
as a comment and therefore will be ignored. (Don't use this convention as a comment; use an exclamation
point (!) for this purpose.)
GDIS(x,y) Random sample of a Gaussian (normal) distribution with mean x and standard deviation y.
SIN(x),
Sine, Cosine, and Tangent of x. x is in radians by default, but can be changed to degrees with
COS(x),
*AFUN.
TAN(x)
SINH(x),
COSH(x), Hyperbolic sine, Hyperbolic cosine, and Hyperbolic tangent of x.
TANH(x)
ASIN(x), Arcsine, Arccosine, and Arctangent of x. x must be between -1.0 and +1.0 for ASIN and
ACOS(x), ACOS. Output is in radians by default, but can be changed to degrees with *AFUN. Range of
ATAN(x) output is -pi/2 to +pi/2 for ASIN and ATAN, and 0 to pi for ACOS.
Arctangent of y/x with the sign of each component considered. Output is in radians by default,
ATAN2(y,x)
but can be changed to degrees with *AFUN. Range of output is -pi to +pi.
VALCHR
Numerical value of CPARM (if CPARM is anumeric, returns 0.0).
(CPARM)
CHRVAL Character value of numerical parameter PARM. Number of decimal places depends on
(PARM) magnitude.
UPCASE
Upper case equivalent of CPARM.
(CPARM)
LWCASE
Lower case equivalent of CPARM.
(CPARM)
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 14/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
To write parameters to a file, use the PARSAV command (Utility Menu>Parameters>Save Parameters).
The parameters file is simply 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
To read parameters from a file use the PARRES command (Utility Menu>Parameters>Restore
Parameters)
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 (Utility Menu>Parameters>Array Parameters>Write to File). The *VWRITE
command command is discussed in Section 3.11.7.
ARRAY
This type is similar to FORTRAN 77 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. This type can have up to
10242-1 rows, up to 255 columns, and up to 7 planes.
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. This type can have up to 10242-1 rows, up to 255 columns, and up to 7 planes.
TABLE
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 15/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
This is a special type of numeric array which allows ANSYS to calculate (through linear interpolation)
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. This type can have
up to 65,535 rows, up to 255 columns, and up to 7 planes.
We can extend these definitions to a three-dimensional 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 identified as (i,j,k). The following figure shows a three-dimensional array.
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 16/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
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:
ANSYS can calculate (through linear interpolation) any values that fall in-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).
A plane index value resides in the 0,0 location for each plane.
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.
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 17/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
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. These values are used
only when accessing data from the array. 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. Again, these values are
used only when accessing data from the array. When setting the array element values, you use the
traditional row and column index numbers.
Row and column index values may be set or changed in any plane, and those values will be applied to all
planes.
This following examples illustrate the *DIM command used to dimension various types of arrays:
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.
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 box.
Reading the values from an ASCII file (*VREAD or *TREAD commands).
The following example shows how to define the element values for the 4x3 array parameter T2, dimensioned
earlier in the *DIM examples:
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
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)
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).
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 19/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
Note-CHAR cannot be used as a character parameter name because it will create a conflict with the CHAR
label on the *DIM command. ANSYS will substitute the character string value 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 ANSYS Commands 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 will vary due to
! random number generation.
Complete instructions for using the dialog box are available from the box's Help button.
Figure 3-5 An example of the *VEDIT dialog box for an ARRAY type array.
Figure 3-5 An example of the *VEDIT dialog box for a TABLE array.
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 20/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
and an array called EXAMPLE that has been dimensioned as 3 x 2, the following commands (provided as
either a part or a macro or input listing)
*VREAD,EXAMPLE(1,1),,,2
(3F6.1)
result in
Note that the *VREAD command cannot be issued directly from the command input window. However, the
Utility Menu>Parameters>Array Parameters>Read from File dialog box offers a way to specify the data
descriptors and issue the command in interactive mode.
Once configured, you have two options for specifying values for the TABLE array elements: you can add
values as you would for any other type of array, or you can read in a table of data from an external file.
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 using the *TREAD command (Utility Menu>Parameters>Array Parameters>Read from File). 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.
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 21/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
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 ANSYS.
You must first define the array in ANSYS, 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;
ANSYS 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
ANSYS array than required, ANSYS will start 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
ANSYS array than required, ANSYS will fill 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.
First, create the 1-D table using the application of your choice (such as a spreadsheet application, a text
editor, etc.) and then save the file as a text file in tab-delimited format. In this example, the table is named
"Tdata" and contains data for time vs. temperature. In its ASCII form, the table would look like this:
Time Temp
0 20
1 30
2 70
4 75
In ANSYS, you define a TABLE parameter "Tt" using the *DIM command (Utility
Menu>Parameters>Array Parameters>Define/Edit). Specify 4 rows and 1 column, row label of Time,
and column label of Temp. Note that the data table you created has four rows and one column of data, plus
the row and column index values (the first column -- TIME - is the row index values) Then read in the file as
described earlier, specifying 2 skipped lines. The TABLE array in ANSYS would look like this:
This same example, done via command input, would look like the following:
*DIM,Tt,table,4,1,1,TIME,TEMP
*TREAD,Tt,tdata,txt,,2
For this example, create (in a spreadsheet application, a text editor, etc.) a 2-D table named "T2data"
containing temperature data as a function of time and x-coordinate and read it into a TABLE array parameter
called "Ttx." The table, in its ASCII form, would look like this:
Time X-Coordinate
0 0 .3 .5 .7 .9
0 10 15 20 25 30
1 15 20 25 35 40
2 20 25 35 55 60
4 30 40 70 90 100
In ANSYS, you define a TABLE parameter "Ttx" using the *DIM command (Utility
Menu>Parameters>Array Parameters>Define/Edit). Specify 4 rows, 5 columns, 1 plane, row label of
TIME, and column label of X-COORD. Note that 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 as described earlier, specifying 2 skipped
lines. The TABLE array in ANSYS would look like this:
This same example, done via command input, would look like the following:
*DIM,Ttx,table,4,5,,time,X-COORD
*TREAD,Ttx,t2data,txt,,2
For this example, create a 3-D table named "T3data" containing temperature data as a function of time, x-
coordinate, and y-coordinate and read it into a TABLE array parameter called "Ttxy." The table, in its ASCII
form, would look like this:
Time X-Coordinate
0 0 .3 .5 .7 .9
0 10 15 20 25 30
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 23/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
1 15 20 25 35 40
2 20 25 35 55 60
4 30 40 70 90 100
1.5 0 .3 .5 .7 .9
0 20 25 30 35 40
1 25 30 35 45 50
2 30 35 45 65 70
4 40 50 80 100 120
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 ANSYS, you define a TABLE parameter "Ttxy" using the *DIM command (Utility
Menu>Parameters>Array Parameters>Define/Edit). 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 4 rows, 5 columns, 2 planes, row label of TIME,
column label of X-COORD, and plane label of Y-COORD. Note that 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 as
described earlier, specifying 2 skipped lines. The TABLE array in ANSYS would look like this for the
second plane of data (Y=1.5):
This same example, done via command input, would look like the following:
*DIM,Ttxy,table,4,5,2,TIME,X-COORD,Y-COORD
*TREAD,Ttxy,t3data,txt,,2
As examples of how ANSYS interpolates values in TABLE arrays, consider the following:
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 24/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
Given that A is a TABLE array parameter, the ANSYS 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 will
then look like this:
ANSYS can calculate (through linear interpolation) force values at times not specified in the FORCE
parameter. For the above example, ANSYS will calculate 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, ANSYS will provide 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 analysis.
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.
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 25/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
You can use the *VGET command (Utility Menu>Parameters>Get Array Data), which is similar to
*GET, to retrieve ANSYS supplied values and store them in an array.
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.
To restore array parameter values, use the *VPUT command (Utility Menu>Parameters>Array
Operations>Put Array Data).
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 description
in the ANSYS Commands Reference.
The ANSYS 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 ANSYS database inconsistent.
As with scalar parameters, you can use the *STATUS command to list array parameters. The following
examples illustrate the *STATUS command in use:
*STATUS
ABBREVIATION STATUS-
ABBREV STRING
SAVE_DB SAVE
RESUM_DB RESUME
QUIT Fnc_/EXIT
POWRGRPH Fnc_/GRAPHICS
ANSYSWEB 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
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 26/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
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)
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.
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 27/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
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
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
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:
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
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 28/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
The second example uses the following previously dimensioned and filled array:
The *VFILL, *VREAD, *VGET, *VWRITE, and *DIM commands were introduced earlier in this
chapter. Other commands that are discussed in this section include
Performs an operation on two input array vectors and produces a single output array vector.
Performs a function on a single input array vector and produces a single output array vector.
Determines the properties of a single input array vector and places the result in a specified scalar
parameter.
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 29/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
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 ANSYS Commands 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)
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.
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 30/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
*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, respectively, 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)
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)
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 31/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
Matrix operations are mathematical operations between numerical array parameter matrices, such as matrix
multiplication, calculating the transpose, and solving simultaneous equations.
Performs matrix operations on two input array parameter matrices and produces one output array
parameter matrix. Matrix operations include
Matrix multiplication
Solution of simultaneous equations
Sorting (in ascending order) on a specified vector in a matrix
Covariance between two vectors
Correlation between two vectors
Copies or transposes an array parameter matrix (accepts one input matrix and produces one output
matrix).
The examples below illustrate the use of some of these commands. Refer to the ANSYS Commands Reference
for syntactical information about these commands.
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 will place 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:
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 32/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
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 will solve the following set of simultaneous
equations:
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)
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)
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 33/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
With the exception of the *VSTAT command, which you cannot access directly in the GUI, all of the
specification commands described below are available via menu path Utility Menu>Parameters>Array
Operations>Operation Settings.
Important: All specification commands are reset to their default settings after each vector or matrix
operation.
*VCUM
Specifies whether results will be cumulative or non-cumulative (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 non-cumulative 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.
*VSTAT
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 N/A No No No
The examples below illustrate the use of some of the specification commands. Refer to the ANSYS
Commands 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:
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)
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 35/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
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 thorugh 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
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:
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 36/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
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.
*vplot,,arrayval(1,1),2
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 37/38
29/10/2019 APDL: Chapter 3: Using Parameters (UP19980820)
mechanika2.fs.cvut.cz/old/pme//examples/ansys55/html/prog_55/g-apdl/AS3.htm 38/38