We will in this tutorial focus mostly on the scripting features available in APDL, as they are one of our main reasons to use APDL instead of other more graphical programs.

We will in this tutorial assume that you are familiar with general programming features like variables, loops, statements etc.


The Ansys finite element solvers enable a breadth and depth of capabilities unmatched by anyone in the world of computer-aided simulation.  Thermal, Structural, Acoustic, Piezoelectric, Electrostatic and Circuit Coupled Electromagnetics are just an example of what can be simulated.  Regardless of the type of simulation, each model is represented by a powerful scripting language … the Ansys Parametric Design Language (APDL).  APDL is the foundation for all sophisticated features, many of which are not exposed in the Workbench Mechanical user interface.  It also offers many conveniences such as parameterization, macros, branching and looping, and complex math operations.  All these benefits are accessible within the Ansys Mechanical APDL user interface. 

Page content

How to run scripts in APDL

Before we begin the actual scripting, let's do a quick tutorial on some of the methods of running scripts in APDL.

Scrips in APDL are usually executed by the use of one of two methods. The first method is to write (or copy & paste) your code directly into the command window available in APDL.

The other method is to read in an input file (txt file) containing your script. To do this, go to File → Read Input From, select the correct file form the menu and click OK.

When locating the correct file, you will often notice that APDL by default opens the wrong directory (e.g. C:USERS when you actually want ../Marine Konstruksjoner/Exercise 7). To fix this, we need to open APDL with our chosen working directory. We may do so by first opening the ANSYS Mechanical APDL Product Launcher and then choose the correct working directory before clicking Run.

Introduction to APDL commands

Although many APDL commands are similar to what we are familiar with from other programming languages, very few have the exact same syntax. This means that to fully understand your code, and to further improve it, you will have to read the APDL commands documentation.

The easiest way to locate the correct documentation is to open Mechanical APDL and click Help → Help Topics. Since we will focus on the scripting part of APDL, the Command reference documentation is the most relevant to us.


As a first example, we would like to obtain the stresses in the node located in the point (L/2, H/2) and write them into our file answers.txt, given the plate below.

The following script includes some simple comments for most commands, but to truly understand the code, we highly recommend you to search them up in the Command Reference as well.

Script.txt
! Author: Chana Sinsabvarodom
! Edited by: Jon Arnt Kårstad
!========================
! Initial programming setup
FINISH
/CLEAR		! Clear all
/PREP7		! Enter preprocessor
/UNITS,SI	! Use SI units

!========================
! Defining the variables
!========================
L=0.6				! Length [m]
H=0.2				! Height [m]
t=0.005				! Thickness [m]
Diameter = H*0.3		! Diameter of hole [m]
Length2hole = L*0.5		! Length to hole [m]
P=-50e6*t			! Load, we will use as a pressure load [Pa] (positive - compression, negative - tension)
mesh_size=0.01			! Mesh size

! Making the plate
K,,0,-H/2,0			! Lower left node
K,,L,-H/2,0			! Lower right node
K,,L,H/2,0			! Upper right node
K,,0,H/2,0			! Upper left node
A,1,2,3,4			! Making an area from our nodes (notice the order)

CYL4,Length2hole,0,Diameter/2,	! Make cylinder
ASBA,1,2			! Remove area 2 (cylinder) from area 1 (plate)

!========================
! Defining the material data (here aluminium)
!========================
MPTEMP,1,0
MPDATA,EX,1,,0.69e11		! Young's modulus [Pa]
MPDATA,PRXY,1,,0.3		! Poisson's ratio [-]
MPDATA,DENS,1,,2700		! Density [kg/m^3]

!========================
! Define local element type
!========================
ET,1,SHELL181			! Shell element, both bending and membrane stresses

!========================
! Connecting area to component
!========================
ASEL,S,LOC,Z,0			! Select area at z = 0
CM,PLATE,AREA			! Group geometry into component
ALLSEL,ALL			! Select all

!========================
! Assigning a thickness to the plate
!========================
SECTYPE,1,SHELL,,PLATE		! Associates section type information with a section ID number.
SECDATA,T,1,0,3			! Given section data
SECOFFSET,MID			! Define section offset for cross section

!========================
! Defining the mesh
!========================
ESIZE,MESH_SIZE			! Element size

TYPE,1				! Set element type pointer
SECNUM,1			! Set element section attribute pointer
CMSEL,S,PLATE,AREA		! Select component named plate (of type area)
AMESH,PLATE			! Mesh plate	

!======================== 
! Load 
!========================
NSEL,S,LOC,X,L			! Select all nodes at x = L
SF,ALL,PRES,P			! Apply pressure load to nodes selected

!========================
! Boundary conditions (Select All X)
!========================
NSEL,S,LOC,X,0			! Select all nodes at x = 0
D,ALL,UX,0,,,,UY,UZ,ROTX,ROTY,ROTZ	! Apply boundary conditions to nodes selected

ALLSEL,ALL

!========================
! Solution			
!========================
! Notice that from now on we write only lower case letters
! APDL does does not differentiate between letter cases (lower or upper, 'A' or 'a')
! It therefore does not matter, but care, it may cause trouble when working with variables
! It is alos adviced to stick to one, making your code better looking.

/solu				! Enter solution processor
solve				! Start a solution
/post1				! Enters database results postprocessor
plnsol,s,eqv			! Display results as continous element contours

!========================
! Write results to text file
!========================
! When writing a file, it is often clever to specify where you want to store the file first
/cwd,'C:\....WRITE YOUR OWN PATH HERE'   	! Changing working directory
*cfopen,answers.txt,,,append			! Open file, append (means add to end of file)

!========================
! Example task 1
!========================	

*vwrite,'Meshsize','XX','YY','XY','Von Mises'	! Write text
(A13,A13,A13,A13,A13,A13)			! A = string
! Above we need to specify how much space we want to give the text. The text is then right-aligned

! x = L/2 and y = H/2 -> mid top node
s1=node(L/2, H/2, 0)				! Select node
*GET,normal_stress_x,node,s1,s,x                ! Results Stress X (sigma_x)
*GET,normal_stress_y,node,s1,s,y                ! Results Stress Y (sigma_y)
*GET,shear_stress,node,s1,s,xy                	! Results Stress XY (tau_xy)
*GET,stress_von_mises,node,s1,s,eqv             ! Results Stress Von Mises

*vwrite,mesh_size,normal_stress_x,normal_stress_y,shear_stress,stress_von_mises
(E13.3,E13.3,E13.3,E13.3,E13.3)			! E = Exponential form

*cfclos						! Close file

The following result file will then be created.

answer.txt
     Meshsize     XX           YY           XY           Von Mise
    0.100E-01    0.481E+08    0.500E+06   -0.686E+05    0.479E+08

Loops and statements in APDL

When doing FEM-analyses, we are often looking to locate e.g. how large our load is before buckling or how small the mesh size has to be before the results converges. If we were to do these tasks manually, it would take forever, and it is for that reason APDL has included loops and statements.

As an example, let's do the analysis presented in the previous section, but for mesh size = 0.10 to mesh size = 0.01 with a step size of 0.01. 

Script.txt
!========================
! Initial programming setup before entering the loop
!========================
FINISH
/CLEAR

!========================
! Defining the variables
!========================
L=0.6				! Length [m]
H=0.2				! Height [m]
t=0.005				! Thickness [m]
Diameter = H*0.3		! Diameter of hole [m]
Length2hole = L*0.5		! Length to hole [m]
P=-50e6*t			! Load, we will use as a pressure load [Pa] (positive - compression, negative - tension)
mesh_size = 0.10		! Initial mesh size

! We only want to write this section on the very top of our file
/cwd,'C:\....WRITE YOUR OWN PATH HERE'   	! Changing working directory
*cfopen,answers.txt,,,append			! Open file, append (means add to end of file)

*vwrite,'Meshsize','XX','YY','XY','Von Mises'	! Write text
(A13,A13,A13,A13,A13,A13)			! A = string

!========================
! Start of loop
!========================
condition = 1					! We want an infinite loop
*DOWHILE, condition				! Regular while loop with condition

*IF,mesh_size,EQ,0.01,EXIT			! If mesh_size == 0.01, exit loop


!========================
! Initial programming setup
!========================

! To clear area, mesh etc, but not all variables, we first write all variables to a separate file
! The reason for this is mainly because we want to keep the mesh_size and our condition
PARSAV,,param		

FINISH
/CLEAR

! After clear, we read in the variables we had previously.
PARRES,,param

/PREP7
/UNITS, SI

!========================
! Making plate
!========================
K,,0,-H/2,0			! Lower left node
K,,L,-H/2,0			! Lower right node
K,,L,H/2,0			! Upper right node
K,,0,H/2,0			! Upper left node
A,1,2,3,4			! Making an area from our nodes (notice the order)

CYL4,Length2hole,0,Diameter/2,	! Make cylinder
ASBA,1,2			! Remove area 2 (cylinder) from area 1 (plate)

!========================
! Defining the material data (here aluminium)
!========================
MPTEMP,1,0
MPDATA,EX,1,,0.69e11		! Young's modulus [Pa]
MPDATA,PRXY,1,,0.3		! Poisson's ratio [-]
MPDATA,DENS,1,,2700		! Density [kg/m^3]

!========================
! Define local element type
!========================
ET,1,SHELL181			! Shell element, both bending and membrane stresses

!========================
! Connecting area to component
!========================
ASEL,S,LOC,Z,0			! Select area at z = 0
CM,PLATE,AREA			! Group geometry into component
ALLSEL,ALL			! Select all

!========================
! Assigning a thickness to the plate
!========================
SECTYPE,1,SHELL,,PLATE		! Associates section type information with a section ID number.
SECDATA,T,1,0,3			! Given section data
SECOFFSET,MID			! Define section offset for cross section

!========================
! Defining the mesh
!========================
ESIZE,MESH_SIZE			! Element size

TYPE,1				! Set element type pointer
SECNUM,1			! Set element section attribute pointer
CMSEL,S,PLATE,AREA		! Select component named plate (of type area)
AMESH,PLATE			! Mesh plate	

!======================== 
! Load 
!========================
NSEL,S,LOC,X,L			! Select all nodes at x = L
SF,ALL,PRES,P			! Apply pressure load to nodes selected

!========================
! Boundary conditions (Select All X)
!========================
NSEL,S,LOC,X,0			! Select all nodes at x = 0
D,ALL,UX,0,,,,UY,UZ,ROTX,ROTY,ROTZ	! Apply boundary conditions to nodes selected

ALLSEL,ALL

!========================
! Solution			
!========================
/solu				! Enter solution processor
solve				! Start a solution
/post1				! Enters database results postprocessor
plnsol,s,eqv			! Display results as continous element contours

!========================
! Write results to text file
!========================
! When writing a file, it is often clever to specify where you want to store the file first
/cwd,'C:\....WRITE YOUR OWN PATH HERE'   	! Changing working directory
*cfopen,answers.txt,,,append			! Open file, append (means add to end of file)

!========================
! Example task 2
!========================	

! x = L/2 and y = H/2 -> mid top node
s1=node(L/2, H/2, 0)				! Select node
*GET,normal_stress_x,node,s1,s,x                ! Results Stress X (sigma_x)
*GET,normal_stress_y,node,s1,s,y                ! Results Stress Y (sigma_y)
*GET,shear_stress,node,s1,s,xy                	! Results Stress XY (tau_xy)
*GET,stress_von_mises,node,s1,s,eqv             ! Results Stress Von Mises

*vwrite,mesh_size,normal_stress_x,normal_stress_y,shear_stress,stress_von_mises
(E13.3,E13.3,E13.3,E13.3,E13.3)			! E = Exponential form

*cfclos						! Close file

mesh_size = mesh_size - 0.01	! Decrease mesh size
*ENDDO				! End of while loop

The following result file will then be created.

answer.txt
     Meshsize     XX           YY           XY           Von Mise
    0.100E+00    0.592E+08    0.203E+07   -0.428E+05    0.582E+08
    0.900E-01    0.552E+08   -0.294E+06    0.300E+06    0.553E+08
    0.800E-01    0.543E+08   -0.671E+06    0.106E+07    0.546E+08
    0.700E-01    0.577E+08   -0.360E+07    0.222E+07    0.597E+08
    0.600E-01    0.618E+08    0.473E+06    0.276E+07    0.617E+08
    0.500E-01    0.605E+08    0.668E+06   -0.158E+07    0.602E+08
    0.400E-01    0.551E+08    0.169E+07    0.149E+07    0.543E+08
    0.300E-01    0.528E+08    0.988E+06    0.199E+05    0.523E+08
    0.200E-01    0.513E+08    0.974E+06    0.538E+05    0.508E+08


File output format

If you're new to APDL, the output formatting may feel a bit weird at first. However, the format descriptors may be written in either FORTRAN or C format, where as we will cover both. Before we begin, I want to remind you that there are a lot of other good documentation on these format descriptors online if you should not find what you are looking for here. Such pages may be this FORTRAN guide by the Michigan Tecnological University or this C guide by cplusplus.com. In addition, ANSYS has included some additional information in their command reference on *vwrite.

Let's first start with the FORTRAN format, which is also what has been used in the previous example scripts. 

The following table includes most of editor descriptors used in FORTRAN. To present it as simple as possible, the following convention of symbols are used:

  • w - the number of positions to be used
  • d - the number of digits to the right of the decimal point
  • e - the number of digits in the exponent part
PurposeDescriptors


Read/write REALs

Decimal formFw.d
Exponential formEw.dEw.dEe
Scientific formESw.dESw.dEe
Engineering formENw.dENw.dEe
Read/write CHARACTERsAAw
White-spacesnX

Although APDL uses FORTRAN formatting, there are some limitations. You may have already spotted one in the previous examples, where the "s" in "Von Mises" has been absent from the file output. The following information are obtained from the APDL command reference.

"Alphanumeric strings are limited to a maximum of 8 characters for any field (A8) using the FORTRAN format. Use the “C” format for string arrays larger than 8 characters. Integer (I) and list-directed (*) descriptors may not be used. You can include text in the format as a quoted string. The parentheses must be included in the format and the format must not exceed 80 characters (including parentheses). The output line length is limited to 128 characters."

The script "Script_output.txt" is used to display some examples using the FORTRAN formatting.

Script_output.txt
!========================
! Write results to text file
!========================
! When writing a file, it is often clever to specify where you want to store the file first
/cwd,'C:\...INSERT YOUR PATH HERE'   		! Changing working directory
*cfopen,answers.txt,,,write			! Open file, append (means add to end of file)


! Since this is an example, we simply specify some values to be outputted
mesh_size = 0.05
normal_stress_x = 0.86E8
normal_stress_y = 0.46E6
shear_stress = 0.21E2
stress_von_mises = 0.74E8

!========================
! Example output 1 - FORTRAN Decimal form
!========================	
*vwrite,'Ex. 1','FORTRAN','Dec.form'
(A8,A8,A8)
*vwrite,'Meshsize','XX','YY','XY','Von Mises'	! Only write this on top
(A13,A13,A13,A13,A13,A13)				! A = string

*vwrite,mesh_size,normal_stress_x,normal_stress_y,shear_stress,stress_von_mises
(F13.3,F13.3,F13.3,F13.3,F13.3)				! F = decimal form

*VWRITE,'' 						! Newline
(A1)

!========================
! Example output 2 - FORTRAN Exponential form
!========================	
*vwrite,'Ex. 2','FORTRAN','Exp.form'
(A8,A8,A8)
*vwrite,'Meshsize','XX','YY','XY','Von Mises'	! Only write this on top
(A13,A13,A13,A13,A13,A13)				! A = string

*vwrite,mesh_size,normal_stress_x,normal_stress_y,shear_stress,stress_von_mises
(E13.3,E13.3,E13.3,E13.3,E13.3)				! E = exponential form

*VWRITE,'' 						! Newline
(A1)

!========================
! Example output 3 - FORTRAN Scientific form
!========================	
*vwrite,'Ex. 3','FORTRAN','Sci.form'
(A8,A8,A8)
*vwrite,'Meshsize','XX','YY','XY','Von Mises'	! Only write this on top
(A13,A13,A13,A13,A13,A13)				! A = string

*vwrite,mesh_size,normal_stress_x,normal_stress_y,shear_stress,stress_von_mises
(ES13.3,ES13.3,ES13.3,ES13.3,ES13.3)			! ES = Scientific form

*VWRITE,''  						! Newline
(A1)

!========================
! Example output 4 - FORTRAN Engineering form
!========================	
*vwrite,'Ex. 4','FORTRAN','Eng.form'
(A8,A8,A8)
*vwrite,'Meshsize','XX','YY','XY','Von Mises'	! Only write this on top
(A13,A13,A13,A13,A13,A13)				! A = string

*vwrite,mesh_size,normal_stress_x,normal_stress_y,shear_stress,stress_von_mises
(EN13.3,EN13.3,EN13.3,EN13.3,EN13.3E4)			! EN = Engineering form

*VWRITE,''  						! Newline
(A1)

!========================
! Example output 5 - FORTRAN Mixture of forms
!========================	
*vwrite,'Ex. 5','FORTRAN','Mixture'
(A8,A8,A8)
*vwrite,'Meshsize','XX','YY','XY','Von Mises'	! Only write this on top
(A13,A13,A13,A13,A13,A13)				! A = string

*vwrite,mesh_size,normal_stress_x,normal_stress_y,shear_stress,stress_von_mises
(F13.3,E13.3,ES13.3,EN13.3,EN13.3)

*VWRITE,''  						! Newline
(A1)

!========================
! Example output 6 - FORTRAN Strings
!========================	
*vwrite,'Ex. 6','FORTRAN','Strings'
(A8,A8,A8)

! FORTRAN can only output 8 alphanumeric strings at once
! The additional space passed (e.g. A20) will then result
! 	in additonal white-spaces on the left side of the string
*vwrite,'123456789','|','123456789','|','123456789'
(A8,A1,A13,A1,A16)

!========================
*cfclos						! Close file

The file "answer.txt" is the resulting file when running the script above.

answer.txt
Ex. 1   FORTRAN Dec.form
     Meshsize     XX           YY           XY           Von Mise
        0.050 86000000.000   460000.000       21.000 74000000.000
 
Ex. 2   FORTRAN Exp.form
     Meshsize     XX           YY           XY           Von Mise
    0.500E-01    0.860E+08    0.460E+06    0.210E+02    0.740E+08
 
Ex. 3   FORTRAN Sci.form
     Meshsize     XX           YY           XY           Von Mise
    5.000E-02    8.600E+07    4.600E+05    2.100E+01    7.400E+07
 
Ex. 4   FORTRAN Eng.form
     Meshsize     XX           YY           XY           Von Mise
   50.000E-03   86.000E+06  460.000E+03   21.000E+00 74.000E+0006
 
Ex. 5   FORTRAN Mixture 
     Meshsize     XX           YY           XY           Von Mise
        0.050    0.860E+08    4.600E+05   21.000E+00   74.000E+06
 
Ex. 6   FORTRAN Strings 
12345678|     12345678|        12345678

The other possibility is to use the C format.

As with the FORTRAN format, we will start out with a table presenting some of the editor descriptors used in C. To present it as simple as possible, the following convention of symbols are used:

  • w - the number of positions to be used
  • d - the number of digits to the right of the decimal point
PurposeDescriptors
Read/write INTEGERSs%wI


Read/write REALs

Decimal form%w.dF
Scientific form%w.dE
Shorter of dec. or sci. form%w.dG
Read/write CHARACTERs%wC
New line%/
Left-justfied text (insert right after %)

-

To distinguish between using the C or FORTRAN format, ADPL has provided the following information.

"The “C” format descriptors are used if the first character of the format descriptor line is not a left parenthesis. “C” format descriptors are up to 80 characters long, consisting of text strings and predefined "data descriptors" between the strings where numeric or alphanumeric character data will be inserted."

The script "Script_output.txt" is used to display some examples using the FORTRAN formatting.

Script_output.txt
!========================
! Write results to text file
!========================
! When writing a file, it is often clever to specify where you want to store the file first
/cwd,'C:\...INSERT YOUR PATH HERE'   		! Changing working directory
*cfopen,answers.txt,,,write			! Open file, append (means add to end of file)


! Since this is an example, we simply specify some values to be outputted
mesh_size = 0.05
normal_stress_x = 0.86E8
normal_stress_y = 0.46E6
shear_stress = 0.21E2
stress_von_mises = 0.74E8

!========================
! Example output 1 - C Decimal form
!========================	
*vwrite,'Ex. 1 C Dec.form'
%c
*vwrite,'Meshsize','XX','YY','XY','Von Mises'
%13c%13c%13c%13c%13c					

*vwrite,mesh_size,normal_stress_x,normal_stress_y,shear_stress,stress_von_mises
%13.3f%13.3f%13.3f%13.3f%13.3f %/

!========================
! Example output 2 - C Scientific form
!========================	
*vwrite,'Ex. 2 C Sci.form'
%c
*vwrite,'Meshsize','XX','YY','XY','Von Mises'
%13c%13c%13c%13c%13c					

*vwrite,mesh_size,normal_stress_x,normal_stress_y,shear_stress,stress_von_mises
%13.3e%13.3e%13.3e%13.3e%13.3e %/

!========================
! Example output 3 - C Scientific & decimal form
!========================	
*vwrite,'Ex. 3 C Shorter of dec. or sci.'
%c
*vwrite,'Meshsize','XX','YY','XY','Von Mises'
%13c%13c%13c%13c%13c					

*vwrite,mesh_size,normal_stress_x,normal_stress_y,shear_stress,stress_von_mises
%13.3g%13.3g%13.3g%13.3g%13.3g %/

!========================
! Example output 4 - C Left-justified text
!========================	
*vwrite,'Ex. 4 C Left-justified text'
%c
*vwrite,'Meshsize','XX','YY','XY','Von Mises'
%-13c%-13c%-13c%-13c%-13c					

*vwrite,mesh_size,normal_stress_x,normal_stress_y,shear_stress,stress_von_mises
%13.3e%13.3e%13.3e%13.3e%13.3e %/

!========================
! Example output 5 - C Customized output
!========================	
*vwrite,'Ex. 5 C'
%c

*vwrite,mesh_size,normal_stress_x
When doing the analysis with a mesh size = %f, I got a sigma_x = %.3e%/

!========================
*cfclos						! Close file

The file "answer.txt" is the resulting file when running the script above.

answer.txt
Ex. 1 C Dec.form
     Meshsize           XX           YY           XY    Von Mises					
        0.050 86000000.000   460000.000       21.000 74000000.000 

Ex. 2 C Sci.form
     Meshsize           XX           YY           XY    Von Mises					
    5.000E-02    8.600E+07    4.600E+05    2.100E+01    7.400E+07 

Ex. 3 C Shorter of dec. or sci.
     Meshsize           XX           YY           XY    Von Mises					
    5.000E-02    8.600E+07    4.600E+05     21.0        7.400E+07 

Ex. 4 C Left-justified text
Meshsize     XX           YY           XY           Von Mises    					
    5.000E-02    8.600E+07    4.600E+05    2.100E+01    7.400E+07 

Ex. 5 C
When doing the analysis with a mesh size = 0.05, I got a sigma_x = 8.6E+07


Visualization and plotting

When creating a visualization to be watched and interpreted by others, an essential parameter is the quality. You will rarely notice that an image is particularly great, but you immidately notice if an image is bad. In this section, we will aim to provide you with some tips and tricks to make your visualizations better and more personalized.

Background color

Reversing the background colors is a quick and easy way to make your images better fit a white paper sheet.

To implement this, add the following code when you're e.g. in the postprocessor.

Reverse video code
/RGB,INDEX,100,100,100, 0	! Reverse video (4 following lines)
/RGB,INDEX, 80, 80, 80,13
/RGB,INDEX, 60, 60, 60,14
/RGB,INDEX, 0, 0, 0,15


  • No labels