Making Thermal Contact Conductance a Parameter in ANSYS Mechanical 18.0 and Earlier with an APDL Command Object

A support request from one of our customers recently was for the ability to make Thermal Contact Conductance, which is sort of a reciprocal of thermal resistance at the contact interface, a parameter so it can be varied in a parametric study.  Unfortunately, this property of contact regions is not exposed as a parameter in the ANSYS Mechanical window like many other quantities are.

Fortunately, with ANSYS there is almost always a way……in this case we use the capability of an APDL (ANSYS Parametric Design Language) command object within ANSYS Mechanical.  This allows us to access additional functionality that isn’t exposed in the Mechanical menus.  This is a rare occurrence in the recent versions of ANSYS, but I thought this was a good example to explain how it is done including verifying that it works.

A key capability is that user-defined parameters within a command object have a ‘magic’ set of parameter names.  These names are ARG1, ARG2, ARG3, etc.  Eric Miller of PADT explained their use in a good PADT Focus blog posting back in 2013

In this application, we want to be able to vary the value of thermal contact conductance.  A low value means less heat will flow across the boundary between parts, while a high value means more heat will flow.  The default value is a calculated high value of conductance, meaning there is little to no resistance to heat flow across the contact boundary.

In order to make this work, we need to know how the thermal contact conductance is applied.  In fact, it is a property of the contact elements.  A quick look at the ANSYS Help for the CONTA174 or similar contact elements shows that the 14th field in the Real Constants is the defined value of TCC, the thermal contact conductance.  Real Constants are properties of elements that may need to be defined or may be optional values that can be defined.  Knowing that TCC is the 14th field in the real constant set, we can now build our APDL command object.

This is what the command object looks like, including some explanatory comments.  Everything after a “!” is a comment:

! Command object to parameterize thermal contact conductance
! by Ted Harris, PADT, Inc., 3/31/2017
! Note: This is just an example. It is up to the user to create and verify
! the concept for their own application.

! From the ANSYS help, we can see that real constant TCC is the 14th real constant for
! the 17X contact elements. Therefore, we can define an APDL parameter with the desired
! TCC value and then assign that parameter to the 14th real constant value.
! We use ARG1 in the Details view for this command snippet to define and enable the
! parameter to be used for TCC.

r,cid ! tells ANSYS we are defining real constants for this contact pair
! any values left blank will not be overwritten from defaults or those
! assigned by Mechanical. R command is used for values 1-6 of the real constants
rmore,,,,,, ! values 7-12 for this real constant set
rmore,,arg1 ! This assigned value of arg1 to 14th field of real constant

! Now repeat for target side to cover symmetric contact case
r,tid ! tells ANSYS we are defining real constants for this contact pair
! any values left blank will not be overwritten from defaults or those
! assigned by Mechanical. R command is used for values 1-6 of the real constants
rmore,,,,,, ! values 7-12 for this real constant set
rmore,,arg1 ! This assigned value of arg1 to 14th field of real constant

You may have noticed the ‘cid’ and ‘tid’ labels in the command object.  These identify the integer ‘pointers’ for the contact and target element types, respectively.  They also identify the contact and target real constant set number and material property number.  So how do we know what values of integers are used by ‘cid’ and ‘tid’ for a given contact region?  That’s part of the beauty of the command object: you don’t know the values of the cid and tid variables, but you alsp don’t need to know them.  ANSYS automatically plugs in the correct integer values for each contact pair simply by us putting the magic ‘cid’ and ‘tid’ labels in the command snippet.  The top of a command object within the contact branch will automatically contain these comments at the top, which explain it:

!   Commands inserted into this file will be executed just after the contact region definition.
!   The type number for the contact type is equal to the parameter “cid”.
!   The type number for the target type is equal to the parameter “tid”.
!   The real and mat number for the asymmetric contact pair is equal to the parameter “cid”.
!   The real and mat number for the symmetric contact pair(if it exists)
! is equal to the parameter “tid”.

Next, we need to know how to implement this in ANSYS Mechanical.  We start with a model of a ball valve assembly, using some simple geometry from one of our training classes.  The idea is that hot water passes through the valve represented by a constant temperature of 125 F.  There is a heat sink represented at the OD of the ends of the valve at a constant 74 degrees.  There is also some convection on most of the outer surfaces carrying some heat away.

The ball valve and the valve housing are separate parts and contact is used to allow heat to flow from the hotter ball valve into the cooler valve assembly:

Here is the command snippet associated with that contact region.  The ‘magic’ is the ARG1 parameter which is given an initial value in the Details view, BEFORE the P box is checked to make it a parameter.  Wherever we need to define the value of TCC in the command object, we use the ARG1 parameter name, as shown here:

Next, we verify that it actually works as expected.  Here I have setup a table of design points, with increasing values of TCC (ARG1).  The output parameter that is tracked is the minimum temperature on the inner surface of the valve housing, where it makes contact with the ball.  If conductance is low, little heat should flow so the housing remains cool.  If the conductance is high, more heat should flow into the housing making it hotter.  After solving all the design points in the Workbench window, we see that indeed that’s what happens:

And here is a log scale plot showing temperature rise with increasing TCC:

So, excluding the comments our command object is 6 lines long.  With those six lines of text as well as knowledge of how to use the ARG1 parameter, we now have thermal contact conductance which varies as a parameter.  This is a simple case and you will certainly want to test and verify for your own use.  Hopefully this helps with explaining the process and how it is done, including verification.




Video Tips: Node and Element IDs in ANSYS Mechanical

This is a common question that we get, particularly those coming from APDL – how to get nodal and element IDs exposed in ANSYS Mechanical. Whether that’s for troubleshooting or information gathering, it was not available before. This video shows how an ANSYS developed extension accomplishes that pretty easily.

The extension can be found by downloading “FE Info XX” for the version XX of ANSYS you are using at…

New Second Edition in Paperback and Kindle: Introduction to the ANSYS Parametric Design Language (APDL)

APDL-Guide-Square-Advert-1After three years on the market and signs that sales were increasing year over year, we decided it was time to go through our popular training book “Introduction to the ANSYS Parametric

I’ll be honest, it was cool to see the book in print the first time, but seeing it on my iPad was just as cool.

Design Language (APDL)” and make some updates and reformat it so that it can be published as a Kindle e-book.   The new Second Edition includes two additonal chapters: APDL Math and Using APDL with ANSYS Mechanical.  The fact that we continue to sell more of these useful books is a sign that APDL is still a vibrant and well used language, and that others out there find power in its simplicity and depth.

This book started life as a class that PADT taught for many years. Then over time people asked if they could buy the notes. And then they asked for a real book. The bulk of the content came from Jeff Strain with input from most of our technical staff. Much of the editing and new content was done by Susanna Young and Eric Miller.

Here is the Description from

The definitive guide to the ANSYS Parametric Design Language (APDL), the command language for the ANSYS Mechanical APDL product from ANSYS, Inc. PADT has converted their popular “Introduction to APDL” class into a guide so that users can teach themselves the APDL language at their own pace. Its 14 chapters include reference information, examples, tips and hints, and eight workshops. Topics covered include:

– Parameters
– User Interfacing
– Program Flow
– Retrieving Database Information
– Arrays, Tables, and Strings
– Importing Data
– Writing Output to Files
– Menu Customization
– APDL Math
– Using APDL in ANSYS Mechanical

At only $75.00 it is an investment that will pay for itself quickly. Even if you are an ANSYS Mechanical user, you can still benefit from knowing APDL, allowing you to add code snippets to your models. We have put some images below and you can also learn more here or go straight to to purchase the paperback or Kindle versions.


PADT-Intro-APDL-pg184-185 PADT-Intro-APDL-pg144-145 PADT-Intro-APDL-pg112-113 PADT-Intro-APDL-pg100-101 PADT-Intro-APDL-pg-020-021


Can I parameterize ANSYS Mechanical material assignments?

So we have known for a long time that we can parameterize material properties in the Engineering Data screen. That works great if we want to adjust the modulus of a material to account for material irregularities. But what if you want to change the entire material of a part from steel to aluminum? Or if you have 5 different types of aluminum to choose, on several different parts, and you want to run a Design Study to see what combination of materials is the best? Well, then you do this. The process includes some extra bodies, some Named Selections, and a single command snippet.
The first thing to do is to add a small body to your model for each different material that you want to swap in and out, and assign your needed material to them. You’ll have to add the materials to your Engineering Data prior to this. For my example I added three cubes and just put Frictionless supports on three sides of each cube. This assures that they are constrained but not going to cause any stresses from thermal loads if you forget and import a thermal profile for “All Bodies”.


Next, you make a Named Selection for each cube, named Holder1, Holder2, etc. This allows us to later grab the correct material based on the number of the Holder.


You also make a Named selection for each group of bodies for which you want to swap the materials. Name these selections as MatSwap1, MatSwap2, etc.


The command snippet goes in the Environment Branch. (ex. Static Structural, Steady-State Thermal, etc.)


! Created by Joe Woodward at PADT,Inc.
! Created on 2/12/2016
! Usage: Create Named Selections, Holder1, Holder2, etc.,for BODIES using the materials that you want to use.
! Create Named Selections called MatSwap1, MatSwap2, etc. for the groups of BODIES for which you want to swap materials.
! Set ARG1 equal to the Holder number that has the material to give to MatSwap1.
! Set ARG2 equal to the Holder number that has the material to give to MatSwap2.
! And so on....
! A value of 0 will not swap materials for that given group.
! Use as is. No Modification to this command snippet is necessary.
 !swap material for Body 1
 /COM,The Named Selection - MatSwap%ARG2% is not set to one or more bodies
 /COM,The Named Selection Holder%ARG1% is not set to one or more bodies
MATSWAP,ARG1,1 !Use material from Holder1 for Swap1
MATSWAP,ARG2,2 !Use material from Holder1 for Swap2
MATSWAP,ARG3,3 !Use material from Holder1 for Swap3
MATSWAP,ARG4,4 !Use material from Holder1 for Swap4
MATSWAP,ARG5,5 !Use material from Holder1 for Swap5
MATSWAP,ARG6,6 !Use material from Holder1 for Swap6
MATSWAP,ARG7,7 !Use material from Holder1 for Swap7
MATSWAP,ARG8,8 !Use material from Holder1 for Swap8
MATSWAP,ARG9,9 !Use material from Holder1 for Swap9


Now, each of the Arguments in the Command Snippet Details corresponds to the ‘MatSwap’ Name Selection of the same number. ARG1 controls the material assignment for all the bodies in the MatSwap1 name selection. The value of the argument is the number of the ‘Holder’ body with the material that you want to use. A value of zero leaves the material assignment alone and does not change the original material assignment for the bodies of that particular ‘MatSwap’ Named Selection. There is no limit on the number of ‘Holder’ bodies and materials that you can use, but there is a limit of nine ‘MatSwap’ groups that you can modify, because there are only nine ARG variables that you can parameterize in the Command Snippet details.


You can see how the deflection changes for the different material combinations. These three steps, holder bodies, Named Selections, and the command snippet above, will give you design study options that were not available before. Hopefully I’ll have an even simpler way in the future. Stay tuned.

Peeling Away the *VMASK

vmask-icon2One way to really unleash the power of APDL is to become familiar, and ultimately fluent, with array parameters. The APDL student will quickly learn that array manipulation involves heavy use of the *V commands, which are used to operate on vectors (single columns of an array). These commands can be used to add two vectors together, find the standard deviation of a column of data, and so on. *V commands consist of what I like to refer to as “action” commands and “setting” commands. The action commands, such as *VOPER, *VFILL, and *VFUN * have their own default behaviors, but these defaults may be overridden by a preceding setting command, such as *VABS, *VLEN, or *VMASK.

*VMASK is one of the most useful, but one of the most difficult to understand, *V command. At its essence it is a setting command that directs the following action command to a “masking” array of true/false values. Only cells corresponding to “true” values in the masking array are considered for the array being operated on in the subsequent action command.

For example, a frequently used application of *VMASK is in the compression of an array—for instance to only include data for selected entities. The array to be compressed would consist of data for all entities, such as element numbers, x-locations for all nodes, etc. The masking array would consist of values indicating the select status for the entities of interest: 1 for selected, –1 for unselected, and 0 for not even in the model to begin with. Only array cells corresponding to a masking array value of 1 would be included in the compression operation, with those corresponding to a value or 0 or –1 being thrown out. Here is a slide from our APDL training class that I hope illustrates things a little better.


Take the class or buy the manual (and review it at Amazon, please!)

What we’ve learned so far is that the masking array contains a list of true/false (or not true) values to refer to when performing its vector operation. But actually, it’s much more general than 1, 0, and –1. What *VMASK does is include cells corresponding to all positive numbers in the masking array (not just +1) and exclude cells corresponding to all values less than or equal to zero in the masking array (not just 0 and            -1), which broadens the possibilities for how *VMASK can be handy.

Everything I’ve used *VMASK for up to this point in my career has involved array compression, and I figured I’d be put out on a sweep meshed ice floe into a sea of CFD velocity streamlines (that’s what happens to old CAE engineers; you didn’t know that?) before I came up with anything else. However, I recently ran into a situation where I needed to add up just the positive numbers in an array. I was about to construct an algorithm that would test each individual number in the array to see if it was positive and, if so, add it to the total. It would’ve been cumbersome. Then I came up with a much less cumbersome approach: use the array as it’s own masking array and then perform the addition operation. Let’s look at an example.

Take the following array:


The sum of all values in the array is 1.5 whereas the sum of just the positive values is 11.5. What’s the most efficient way to have APDL calculate each?

In the case of summing all values in the array, it’s easy, just simply execute


which gives you


But what about summing just the positive values? That’s easy, just use SUM_EXMPL as its own masking array so that only the positive values are included in the operation.




Boo yeah

Now why was I doing this? I had to create a macro to calculate total nodal loads for an unconstrained component in just the positive direction (to ignore the loads counteracting in the negative direction), and this was my approach. Feel free to download the macro: facelds.mac and try it out yourself.

Quick Tip: Concatenating Text Files Using ANSYS Mechanical APDL

So you have text output from some ANSYS analysis and you wish you could just do this:

cat lift.txt  cop.txt drag.txt >> results.txt

and you are writing an ANSYS macro and want it to run on all platforms.  The following macro will use APDL commands to join the files together. 



















Bonus: If you want to strip some lines off of the top or read less than all the lines, you can pass additional arguments to *sread:






Serial and Parallel ANSYS Mechanical APDL Simulations

ANSYS-APDL-Macro-PeDALThere are times when you want to study the effects of varying parameters.  If you have an existing MAPDL script that is parameterized, the following procedure will allow you to easily run many variations in an organized manner. 

Let’s assume a parameterized MAPDL macro called build_solve that does something you want to simulate many times and has 2 variables called power and scale which are set with argument 1 and 2 respectively.  Running this macro with the classic interface, with power=30 and scale=2.5 would look like this:


Next, create a MAPDL macro to launch all of the simulations.  This script could be named control.mac.  The first thing to do here is to create arrays of your parameters and assign values to them.  This example will vary power and scale.  Here are the arrays of values that will be passed to build_solve:





Most of the control.mac commands will be put inside of nested *do loops.  There will be a *do loop for each of parameters being varied.



Next, use *cfopen to set up the arguments to be passed to build_solve.  Each time through the *do loops will create a new run1.mac







One of the key features of this approach is to run anywhere and build directories below the working directory.  Use the /inquire command to store the current directory name.


Use *cfopen to create a string that will be used for the directory name.  By using the variables as part of the string, the directories will have unique names.  A time or date stamp could also be included in this string.  This macro is executed immediately to create the string dirnam for use in the commands subsequently.







Eventually, the resulting directory structure will look something like the image below.  Each directory will contain a separate simulation with the arguments of power and scale set respectively.


The last *cfopen creates a windows batch file which will (when executed)

  1. Create the new directory

  2. Copy all of the macro files from the working directory into the new directory (including run1.mac)

  3. Change into the new directory using CD

  4. Launch ansys in batch mode, in this case using a gpu and 12 cpus, using the run1.mac input and outputting to f.out

  5. Change back to the working directory (ready to do it all again)

The code for the windows batch file is:





COPY *.mac "%C\%S"


CD "%C\%S"


"C:\Program Files\ANSYS Inc\v150\ansys\bin\winx64\ansys150" -b -acc nvidia -np 12 -i run1.mac -o f.out


CD "%C"


The last step is to run the windows batch file.  /sys is used to make this system call.  If the simulation is not well parallelized and you have enough licenses available, run the simulations in low priority mode immediately.  This will launch all of your simulations in parallel:

  • /sys,start /b /low rfile.bat

If the model is well parallelized (in other words, it will use your system’s gpu/cpus/RAM efficiently) or you only have 1 license available, launch the batch files in high priority mode and use the /wait option which will insure that windows waits for the job to finish before launching the next simulation.

  • /sys,start /b /high /wait rfile.bat

You can download and view the examples control.mac and build_solve.mac from this zip file:

Introduction to APDL Book Turns One

PADT-Intro-APDL-coverWe got our monthly report from Amazon on our book  “Introduction to the ANSYS Parametric Design Language (APDL)” and we noticed that it has been one year since we published it.  This was our first foray into self publishing so we thought it was worth noting that it has been a year.

Being engineers, we are kind of obsessed with numbers.  The first number is a bit discouraging, 194 units sold.  That is not going to make any best seller lists (more on lessons learned below).  51% were sold on, 19% by Amazon Europe, and 16% on Amazon UK, with 13% sold by non-Amazon affiliates.  

Lessons Learned

This is our first time doing self publishing we have learned some lessons worth sharing:

  1. You can’t publish a work document as an e-book.  
    We figured we would format it for a paper book, then just publish the same file as an e-book.  WRONG.  The formatting, didn’t translate at all. If it was a novel, it would have worked fine, but with all the figures and code, it was a mess. So we took it off the site.  We have received feedback that this has kept some people from buying the book.
  2. Reviews matter.
    We got one review, and it was not good because they bought the E-Book (see 1).We have resisted the temptation to publish our own review… everyone does it… It would be great if anyone reading this could put up a review.
  3. We should have done this 5 years ago.
    The reality is that APDL usage is down as ANSYS Mechanical keeps getting better and better.  So the need to do advanced APDL scripting is not what it used to be. Plus, many new users are never exposed to APDL.
  4. Amazon fiddles with your price.
    It may or may not be a bad thing, but Amazon lowers your price if their affiliates start selling a book for less than you originally set the price at.  So the initial $75 price has gone as low as $55 when demand was high (several copies a week!).  In that the whole thing is an experiment, this has caused no grief but it is something to be aware of.
  5. Overall, the whole process was easy and a nice business model
    Let’s be honest, there is not a huge demand for a book like this. The (owned by Amazon) model is a great model for niche publishing like this. It was easy to upload, easy to monitor, and those fat royalty checks (what is the emoticon for sarcasm?) come in once a month. The best part is that because it is print-on-demand, there is no need pay for an inventory up front.

If you don’t have a copy (and only 190 some of you do so I’m guessing you don’t) head on over to our page on amazon and check it out.  You can spin it around and see the front and back cover!

If you are one of the select few, maybe write a review and help us out a bit?

Making APDL Parameters Available in the ANSYS Parameter Manager or DesignXplorer: Prep, Solve, and Post

This is one of those questions that comes up every once in a while that is not so obvious at first glance, but that is simple once you understand how ANSYS Mechanical interacts with ANSYS Mechanical APDL.  After a couple of email exchanges around a tech support question, we thought it would be good to share with everyone.

Before we get started, if you need a refresher on Command Objects in ANSYS Mechanical, the way in which you send APDL commands to the ANSYS Mechanical APDL solver, here is a seminar from a couple of years ago that covers the whole deal:

The basic problem is this: you have an APDL script you execute as a command object that does some sort of model interrogation or stores the result of some calculation, and you want to use that parameter in the parameter manager or in DesignXplorer.  If you look at the details view for a command object you will notice that it only supports input parameters: ARG1-ARG9.


If you look at the example (silly) macro you will see that it:

  1. Grabs component (named selection) END1
  2. Figures out how many nodes are attached to END1 (NMND)
  3. Takes ARG1 as the total load applied load
  4. Calculates the per node load by dividing the total load by the number of loads.
  5. Applies that per node load
  6. Reselects all the nodes

If I want to know how many nodes I put the load on and what the per node load is I’m kind of stuck here.  Any command object you add to the tree above the Solution branch only allows input parameters.

But a command snippet applied in the Solution branch is different, it allows you to pull parameters back and share them through the parameter manager.

When you first insert a command object you only get input parameters (ARG1-ARG9) as usual, and an empty section called “Results”


The way you get result parameters, or what I think should be called “Output Parameters” is you create a parameter in the command object’s APDL script that starts with “my_”  When you click outside the text input window the program parses you script and if it finds any “my_” parameters in the text, it sticks them in the Results section:


Note, the default is “my_” but you can change it n the “Output Search Prefix” line in the Definition block.

Initially they will show up pinkish because the model has not been run and they are not defined. Click on the box to make them parameters that get passed outside of the program and then run:


If you pop back out to the project view you will see that we now have a Parameter Set bar with both input and output parameters:


And if you open the parameter manager up you can see the input and output parameters:


This works because all ANSYS mechanical is doing is making one big batch input file for ANSYS MAPDL.  That file contains any command objects you insert into the tree and extracts any parameters that you tagged in a post processing command object for return to ANSYS Mechanical.

20 APDL Commands Every ANSYS Mechanical User Should Know

One of the most powerful things about ANSYS Mechanical is the fact that it creates an input file that is sent to ANSYS Mechanical APDL (MAPDL) to solve. This is awesome because you as a user have complete and full access to the huge breadth and depth available in the MAPDL program.  MAPDL is a good old-fashioned command driven program that takes in text commands one line at a time and executes them. So to access all those features, you just need to enter in the commands you want.

For many older users this is not a problem because we grew up using the text commands. But new users did not get the chance to be exposed to the power of APDL (ANSYS Parametric Design Language) so getting access to those advanced capabilities can be tough. 

In fact, I was in a room next to one of our support engineers while they were showing a customer how to change the elements that the solver would solve (Mechanical defaults to the most common formulation, but you can change them to whatever still makes sense) and the user had to admit he had never really used or even seen APDL commands before. 

So, as a way to get ANSYS Mechanical users out there started down the road of loving APDL commands, we got together and came up with a list of 20 APDL commands that every user should know.  Well, actually, it is more than 20 because we grouped some of them together.  We are not going to give too much detail on their usage, the APDL help is fantastic and it explains everything.  In fact, if you use a copy of PeDAL you can get the help right there live as you type (yes, that was a plug for you to go out and plop down $49 and buy PeDAL).

Also note that we are not getting in to how to script with APDL. It is a truly parametric command language in that you can replace most values in commands with parameters. It also has control logic, functions and other capabilities that you find in most scripting languages.  We will focus on actual commands you use to do things in the program here. If you want to learn more about how to program with APDL, you can purchase a copy of our “Introduction to the ANSYS Parametric Design Language” book. (another plug)

Some APDL Basics

APDL was developed back in the day of punch cards.  It was much easier to use than the other programs out there because the commands you entered didn’t have to be formatted in columns.  Instead arguments for commands are separated by commas.  Therefore, instead of defining a Node in your model as:

345   12.456    17.4567   0.0034 

(note that the location of that decimal point is critical). You create a line as:

N,345,12.456,17.4567, 0.0034

Trust me, that was a big deal. But what you need to know now is that all APDL commands start with a keyword and are followed by arguments. The arguments are explained in the Command Reference in the help.  So the entry for creating a node looks like this:


The documentation is very consistent and you will quickly get the hang of how to get what you need out of it.  The layout is explained in the help:  // Command Reference // 3. Command Dictionary

Another key thing to know about commands in MAPDL is that most entities you create (not loads and boundary conditions) have an ID number. You refer to entities by their ID number.  This is a key concept that gets lost if you grew up using GUI’s.  So if you want to make a coordinate system and use it, you define an ID for it and then refer to that ID. Same thing goes for element definitions (Element Types), material properties, etc…  Remember this, it hangs up a lot of newer users.

To use MAPDL commands you simply enter each command on a line in a command object that you place in your model tree. We did a seminar on this very subject about two years ago that you can watch here.

The idea of entity selection is fundamental to APDL.  Above we point out that all entities have an ID.  You can interact with each entity by specifying its ID.  But when you have a lot of them, like nodes and elements, it would be a pain.  So APDL deals with this by letting you select entities of a given type and making them “selected” or “unselected”  Then when you execute commands, instead of specifying an ID, you can specify “ALL” and all of the selected entities are used for that command.  Sometimes we refer to entities as being selected, and sometimes we refer to them as “active.”  The basic concept is that any entity in ANSYS Mechanical APDL can be one of two states: active/selected or inactive/unselected.  inactive/unselected entities are not used by whatever command you might be executing.

If you want to see all of the APDL command that ANSYS Mechanical writes out, simply select the setup branch of your model tree and choose Tools->Write Input File.  You can view it in a text editor, or even better, in PeDAL.


One last important note before we go through our list of commands: the old GUI for MAPDL can be used to modify or create models as well as ANSYS Mechanical. Every action you take in the old GUI is converted into a command and stored in the jobname.log file.  Many users will carry out the actions they want in an interactive session, then save the commands they need from the log file.

Wait, one more thing:  Right now you need these commands. But at every release more and more of the solver is exposed in ANSYS Mechanical FUI and we end up using less and less APDL scripts.  So before you write a script, make sure that ANSYS Mechanical can’t already do what you want.

The Commands

1. !

An exclamation point is a comment in APDL. Any characters to the right of one are ignored by the program. Use them often and add great comments to help you and others remember what the heck you were trying to do.


The MAPDL program consists of a collection of 10 processors (there were more, but they have been undocumented.) Commands only work in some processors, and most only in one.  If you enter in a preprocessor command when you are in the postprocessor, you will get an error.

When you create a command object in your ANSYS Mechanical model, it will be executed in either the Pre processor, the Solution processor, or in the Post processor.  Depending on where in the model tree you insert the command object.   If you need to go into another processor you can, you simply issue the proper command to change processors.  JUST REMEMBER TO GO BACK TO THE PROCESSOR YOU STARTED IN when you are done with your commands.

/PREP7 – goes to the pre processor. Use this to change elements, create things, or modify your mesh in any way.

/SOLU – goes to the solution processor.  Most of the time you will start there so you most often will use this command if you went into /PREP7 and need to get back. Modify loads, boundary conditions, and solver settings in this processor.

/POST1 – goes to the post processor. This is where you can play with your results, make your own plots, and do some very sophisticated post-processing.

FINISH – goes to the begin level. You will need to go there if you are going to play with file names.


You only really need to know these commands if you will be making your own elements… but one of those things everyone should know because the assignment of element attributes is fundamental to the way APDL works…. so read on even if you don’t need to make your own elements.

Every element in your model is assigned properties that define the element.  When you define an element, instead of specifying all of its properties for each element, you create definitions and give them numbers, then assign the number to each element.  The simplest example are material properties. You define a set of material properties, give it a number, then assign that number to all the elements in your model that you want to solve with those properties.

But you do not specify the ID’s when you create the elements, that would be a pain. Instead, you make the ID for each property type “active” and every element you create will be assigned the active ID’s. 

The commands are self explanatory: Type sets the Element Type, MAT sets the material ID, REAL set the real constant number, and SECNUM sets the active section number. 

So, if  you do the following:


you get:

      1  34   4   2   0 112      1     2     3     4    11    12    13    14
      2   3   4   4   0 200    101   102   103   104   111   112   113   114

4. ET

The MAPDL solver supports hundreds of elements.   ANSYS Mechanical picks the best element for whatever simulation you want to do from a general sense.  But that may not be the best for your model. In such cases, you can redefine the element definition that ANSYS Mechanical used.

Note: The new element must have the same topology. You can’t change a 4 noded shell into an 8 noded hex.  But if the node ordering is the same (the topology) then you can make that change using the ET command. 


If you define a real constant, element type, or material ID in APDL and you want to change a bunch of elements to those new ID’s, you use EMODIF.  This is the fastest way to change an elements definition.


Probably the most commonly needed APDL command for ANSYS Mechanical users are the  basic material property commands. Linear properties are defined with MP command for a polynomial vs. temperature or MPDATA and MPTEMP for a piece-wise linear temperature response.  Nonlinear material properties are defined with the TB, TBDATA, and TBTEMP commands.

It is always a good idea to stick your material definitions in a text file so you 1) have a record of what you used, and 2) can reuse the material model on other simulation jobs.


If you define an elements formulation with options on the ET command, and the material properties on the material commands, where do you specify other stuff like shell thickness, contact parameters, or hourglass stiffness?  You put them in real constants.  If you are new to the MAPDL solver the idea of Real constants is a bit hard to get used to. 

The official explanation is:

Data required for the calculation of the element matrices and load vectors, but which cannot be determined by other means, are input as real constants. Typical real constants include hourglass stiffness, contact parameters, stranded coil parameters, and plane thicknesses.

It really is a place to put stuff that has no other place.  R creates a real constant, and RMODIF can be used to change them.


As mentioned, selection logic is a huge part of how MAPDL works.  You never want to work on each object you want to view, change, load, etc… Instead you want to place entities of a given type into an “active” group and then operate on all “active” entities. (you can group them and give them names as well, see CM-CMSEL-CMDELE below to learn about components)

When accessing MAPDL from ANSYS Mechanical you are most often working with either nodes or elements.  NSEL and ESEL are used to manage what nodes and elements are active. These commands have a lot of options, so review the help.


You often select nodes and then need the elements attached to those nodes. Or you select elements and you need the nodes on those elements.  NSLE and ESLN do that.  NSLE selects all of the nodes on the currently active elements and ESLN does the opposite.


A very common mistake for people writing little scripts in APDL for ANSYS Mechanical is they use selection logic to select things that they want to operate on, and then they don’t remember to reselect all the nodes and elements.  If you issue an NSEL and get say the nodes on the top of your part that you want to apply a load to. If you just stop there the solver will generate errors because those will be the only active nodes in the model. 

ALLSEL fixes this. It simply makes everything active. It is a good idea to just stick it at the end of your scripts if you do any selecting.

11. CM – CMSEL

If you use ANSYS Mechanical you should be very familiar with the concept of Named Selections. These are groups of entities (nodes, elements, surfaces, edges, vertices) that you have put into a group so you can scope based on them rather than selecting each time. In ANSYS MAPDL these are called components and commands that work with them start with CM.

Any named selection you create for geometry in ANSYS Mechanical gets turned into a nodal component – all of the nodes that touch the geometry in the Named Selection get thrown into the component. You can also create your own node or element Named Selections and those also get created as components in MAPDL. 

You can use CM to create your own components in your APDL scripts.  You give it a name and operate away.  You can also select components with the CMSEL command.

12. *GET

This is the single most awesomely useful command in APDL.  It is a way to interrogate your model to find out all sorts of useful information: number of nodes, largest Z value for node position, if a node is selected, loads on a node, result information, etc… 

Check out the help on the command. If you ever find yourself writing a script and going “if I only knew blah de blah blah about my model…” then you probably need to use *get.


Coordinate systems are very important in ANSYS Mechanical and ANSYS MAPDL.  In most cases you should create any coordinate systems you need in ANSYS Mechanical. They will be available to you in ANSYS MAPDL, but by default ANSYS Mechanical assigns a default ID. To use a coordinate system in MAPDL you should specify the coordinate system number in the details for a given coordinate system by changing “Coordinate System” from “Program Defined” to “Manual” and then specifying a number for “Coordinate System ID”


If you need to make a coordinate system in your APDL script, use the LOCAL command. 

When you want to use a coordinate system, use CSYS to make a given coordinate system active.

Note: Coordinate system 0 is the global Cartesian system. If you change the active coordinate system make sure you set it back to the global system with CSYS,0

RSYS is like CSYS but for results. If you want to plot or list result information in a coordinate system other than the global Cartesian, use RSYS to make the coordinate system you want active.


One thing to be very aware of is that each node in a model has a rotation associated with it. By default, the UX, UY, and UZ degrees of freedom are oriented with the global Cartesian coordinate system. In ANSYS Mechanical, when you specify a load or a boundary condition as normal or tangent to a surface, the program actually rotates all of those nodes so a degree of freedom is normal to that surface.

If you need to do that yourself because you want to apply a load or boundary condition in a certain direction besides the global Cartesian, use NROTATE.  You basically select the nodes you want to rotate, specify the active coordinate system with CSYS, then issue NROTATE,ALL to rotate them.

Be careful though. You don’t want to screw with any rotations that ANSYS Mechanical specified.

15. D

The most common boundary condition is displacement, even for temperature.  To specify those in an ANSYS MAPDL script, use the D command.  Most people use nodal selection or components to apply displacements to multiple nodes.

In its simplest form you apply a single value for displacement to one node in one degree of freedom.  But you can specify multiple nodes, multiple degrees of freedom, and more powerfully, the value for deflection can be a table. Learn about tables here.

16. F

The F command is the same as the D command, except it defines forces instead of displacement.  Know, it, use it.

17. SF – SFE

If you need to apply a pressure load, you use either SF to apply to nodes ore SFE to apply to elements. It works a lot like the D and F commands.


When the ANSYS MAPDL solver is solving away it writes bits and pieces of information to a file called jobename.out, where jobname is the name of your solver job.  Sometimes you may want to write out specific information, say list the stresses for all the currently selected nodes, to a file. use /OUTPUT,filename to redirect output to a file. When you are done specify /OUTPUT with no options and it will go back to the standard output.

19. /SHOW

ANSYS MAPDL has some very sophisticated plotting capabilities.  There are a ton of command and options used to setup and create a plot, but the most important is /SHOW,png.  This tells ANSYS MAPDL that all plots from now on will be written in PNG format to a file. Read all about how to use this command, and how to control your plots, here.



The ANSYS MAPDL solver solves for a lot of values. The more complex the element you are using, the more the number of values you can store.  But how do you get access to the more obscure ones? ETABLE.  Issue 38 of The Focus from 2005 goes in to some of the things you can do with ETABLE.

Where to go From Here

This is certainly not the definitive list.  Ask 20 ANSYS MAPDL users what APDL commands all ANSYS Mechanical users should know, and you might get five or six in common. But based on the support calls we get and the scripts we write, this 20 are the most common that we use.

Command help is your friend here.  Use it a lot.

The other thing you should do is open up ANSYS MAPDL interactively and play with these commands. See what happens when you execute them.

Introduction to the ANSYS Parametric Design Language (APDL) Book Now Available on Amazon!

PADT-Intro-APDL-Amazon-PagePADT’s popular “ANSYS Customization with the ANSYS Parametric Design Language Guide” Has been updated and reformatted as a book and published as “Introduction to the ANSYS Parametric Design Language”  in both softcover and Kindle formats.

This book started life as a class that PADT taught for many years. Then over time people asked if they could buy the notes.  And then they asked for a real book.  The bulk of the content came from Jeff Strain with input from most of our technical staff.  Much of the editing and new content was done by Susanna Young and Eric Miller.

Here is the Description from

The definitive guide to the ANSYS Parametric Design Language (APDL), the command language for the ANSYS Mechanical APDL product from ANSYS, Inc. PADT has converted their popular “Introduction to APDL” class into a guide so that users can teach themselves the APDL language at their own pace. Its 12 chapters include reference information, examples, tips and hints, and eight workshops. Topics covered include:
– Parameters
– User Interfacing
– Program Flow
– Retrieving Database Information
– Arrays, Tables, and Strings
– Importing Data
– Writing Output to Files
– Menu Customization

At only $75.00 it is an investment that will pay for itself quickly.  Even if you are an ANSYS Mechanical user, you can still benefit from knowing APDL, allowing you to add code snippets to your models. We have put some images below and you can also learn more and purchase your copy on  They can ship anywhere in the world.







Saving Mechanical APDL Plots in a Design Study

One of the cool features in the ANSYS Workbench is the ability to set up a design study and kick off a bunch of runs that bring back key parameters.  This is great for a design exploration but sometimes you actually would like a result plot, or maybe the info in a text file as well.  When a design study is done, unless you tell Workbench to save all your run files, it deletes all the files.

To do the posting on ICEM CFD in the workbench project page, I needed to do just that, so I thought I would share my method in case others want to use it.

The way I do it is pretty simple:

  • Use a /INQUIRE to get the directory the run is running in
  • Use some string functions to get the name of the design point from the directory name
  • Temporarily change the jobname
  • Save my plots
  • Change the jobname back to file
  • Copy the files to the User_Files directory.

Here is what it looks like:

   1: /post1

   2: set,last

   3: finish

   4: /inquire,aa,directory

   5: ii = strpos(aa(1),'\dp')

   6: ij = strpos(aa(ii+1),'\')-1

   7: dpn = strsub(aa(1),ii+1,ij)

   8: dpn = strcat(dpn,'_')

   9: /file,dpn

  10: /post1

  11: /view,1,1,1,1

  12: /vup,1,z

  13: /show,png

  14: eplot

  15: plnsol,u,sum

  16: /show,close

  17: /sys,copy *.png ..\..\..\user_files

  18: finish

  19: /file,file

See how it uses /inquire to get the directory, then strpos(), strsub(), and strcat() to get the design point name.  Then it simply changes the file name, does a /show,png and plots. The results are copied using a system command.

Two important things to note:

  1. You have to do the set command before you change the jobname, otherwise your RST files will not work
  2. This version is written for windows, you need to use forward slashes and cp for Linux.

You can attach this to a MAPDL system or as a code snippet.

Beware the ARGS, Matey!!

Pirate Joke:
One day me ARG says, “ARG, go to ARG and get the ARG to ARG the mainsail.” I says to me ARG, “ARG went yesterday. The ARG is over yonder by the ARG and the rum! Ha-ha-ha-ha-ARG!!”

Yeah… pirate jokes don’t work so well when the same ARG is used in too many places. The same goes for command snippets.

Summary Note: This article got longer than I intended, so here is a summary of the important points.

1. When using multiple Command Objects in a single mechanical session, the ARG variables initialized in earlier scripts are still active in later snippets if the ARG values for that snippet are not filled in the details window. Don’t assume the ARG values are zero, unless you set them to zero.

2. Output arguments are evaluated at the end of the MAPDL run. If the same variable name is used in multiple command objects, all the snippets will show the same output value, which is the value of that variable at the end of the solution process.

Now you can keep reading if you’re bored, or curious, or just confused. Smile

Up until a few days ago, I was under the impression that each command snippet that was added to a Workbench Mechanical had it’s own set of ‘ARG’ variables, like MAPDL does for macros, since each one has a details window with it’s own set of ARG Variables. Well, they don’t.


When you hit the ‘Solve’ button in Mechanical, it builds one large input file that it sends to MAPDL. This input file contains all the nodes and elements, loads and supports. It also contains any command snippets that you have in the model. All command snippets are run in the main namespace. ARGS from one snippet carry over to another.

As an example I set up a small command snippet with the details from the above picture. It uses two arguments, ARG1 and ARG2.  Below shows exactly what get added to the overall input file.



The first two lines are added by Workbench to initialize the variables. All looks good and works fine, until I add another command snippet.  This one is even simpler and just stores the ARG variable to defined variables that Workbench will then read back to the details window, which is discussed below.


As you can see below, the ARG1 and ARG2 variables are left blank, but the two output variables match what was set in the previous command snippet.  This is because the*SET commands that Workbench adds, are only added when the details window has values given. So ARG1 and ARG2 are never overwritten from the previous command snippet.  The way to avoid the overlapping of input variables is to fill in the Input Arguments with zeros whenever using multiple command snippets.



Which brings up another point, about output variables. As many of you know, but some may not, each command snippet has a “Parameter Search Prefix”, which is set to “my_” by default. This allows Mechanical to search through your snippet and find any variables that you define that start with “MY_”. In the example above, the output variables are MY_ARG1 and MY_ARG2. (Remember that MAPDL stores all variable in uppercase.) The values of these variables are then pulled out of the MAPDL database and shown in the details window for that command snippet.  The values are taken at the end of the solution phase, and not at the time they are defined. So this means that if two or more command objects use the same output variable names, whatever value the last command object set for the variables, that is going to be the same value read back in and displayed for all of the command objects using that variable. The best way to avoid this is to use different output variable names in each command object.

Since I already gave you the good points in the summary, I won’t restate them here. I will just add that command objects are great for adding functionality to your Workbench Mechanical runs. Just be cautious ARGS when using multiple objects. (Or pirate jokes, for that matter.)