ANSYS Mechanical Scripting: HOWTO Part 1


Over the past 10+ years, ANSYS has steadily migrated more and more functionality into the DesignSpace, wait Workbench… no I mean Workbench Simulation or rather now ANSYS Mechanical product line.  If you’ve used ANSYS in the last 5 years you’ve probably come to know this interface as Workbench, and you’ve probably delineated it in your mind as standing in opposition to the old interface, “Classic” or Mechanical APDL.  Perhaps these qualities of each interface come to mind for you as they do for me

Mechanical APDL is:

  1. Old looking and visually clunky.
  2. Quirky, but powerful.
  3. The only thing “real” analyst use.
  4. Scriptable, Scriptable and More Scriptable. 

ANSYS Mechanical is:

  1. Cool, slick looking user interface
  2. Super easy to use when your analysis is supported out-of-the-box.
  3. Great meshing and geometry support.
  4. Not scriptable.

Fortunately for us the margin in capabilities between Mechanical APDL and ANSYS Mechanical is narrowing at each release and so more and more “real” analyst are turning to ANSYS Mechanical for their simulation needs.   However, one glaring difference between the two products that has remained virtually unchanged since the beginning is in the area of scripting.   Mechanical APDL is scriptable at its core.  In fact, that is the only way I personally interact with the program, which I’m sure is true for many of you as well.  ANSYS Mechanical on the other hand appears as though it is just an impenetrable black box.  It does what it does and that is that.  Fortunately, that is only partially true.  The reality is there is a whole underworld that exists in ANSYS Mechanical that is scriptable, it is just very cleverly and discretely hidden.  (i.e. It isn’t documented)  ANSYS, Inc. plans to keep it that way the best I can tell.  However, I’ve spent the last few months of my life painstakingly pulling back the layers and peeking inside.  So, I hope to show you some interesting tidbits I’ve found along the way.

Anatomy of DesignSpace

Why am I going back to calling ANSYS Mechanical DesignSpace?  Well, as you might imagine, developers aren’t quite as flexible as the marketing types, so a lot of the code that is ANSYS Mechanical still carries the moniker DesignSpace, or DS.  You can imagine the mutiny that would occur, if every time a suit got the bright idea to change a product name, all the developers were required to rewrite their code to reflect the new name.  It ain’t happening.

So, what does DS look like on the inside?  Well, the best I can tell it is architected this way:


The outer shell (aka the impenetrable black box) is the GUI.  Obviously, this is how the user typically interacts with the program.  However, the GUI itself is not a statically compiled piece of executable code.  It is more like an interpreter that builds itself every time you launch ANSYS Mechanical. (You may be asking yourself, “Self, is this why it takes so bloody long to load…”  Self replies “Perhaps…  BTW, I need more coffee.”)  So, the next logical question is “How does it know what to build?”  I’m glad you asked, because this turns out to be one of the keys to unlocking the black box.  The structure of the ANSYS Mechanical GUI is described in a handful of XML files.  This is important for a couple of reasons:

  1. XML is just text, so you don’t have to put on your binary glasses to read it.
  2. XML has structure. Brains really like structure.

It may seem like I’m getting nowhere fast with this, but hang with me.  Where we are at now is that the structure of the GUI is described by an XML file.  So what that means is that the text associated with all of the menus and buttons in the GUI; whether a GUI entity is a toolbar, or a toolbar button or a menu item; all of that is described textually inside these XML files.  However, a GUI that doesn’t interact with the user is just a G.  How does the UI come into play? 

I’m glad you asked that as well.  The interactive part of the ANSYS Mechanical UI is handled primarily through the use of javascript.  Javascript is an interpreted scripting language that is most popular in the context of web development.  It is text based, i.e. it isn’t compiled.  The way it works is that there is a javascript interpeter built into the ANSYS Mechanical executable.  Almost all of the core functionality of ANSYS Mechanical is implemented as a set of C++ libraries.  These are just great big pieces of code like meshing, or virtual topology, or graphics or geometry selection that expose a set of routines that hook into the javascript interpreter.  All of these functional pieces are then glued together with javascript.  Thus, it turns out that the UI part of the ANSYS Mechanical GUI is just a whole bunch of javascript code juggling all of these big pieces of functionality that are implemented in C++.  It is not completely unlike Mechanical APDL, where a function like ASBW hides a complex surface-to-surface intersection routine followed by a BREP patchup; however, we simply know it as “Divide these areas by the working plane.”   In the same way there are various javascript calls that a script can issue that will insert a new boundary condition, for example. Or, perhaps, change a mesh control and re mesh.

Finally, I’ll leave you with one last piece of the puzzle for this post, then we’ll pick it up with examples in the next post.   You remember that I said that the GUI is cooked up each time using an XML file as the recipe.  Inside that XML file are definitions for javascript functions that are called whenever a user clicks on a button, or selects a menu item.  This provides the link between the static GUI structure and the dynamic user interaction.  This is how we turn the key to unlock the black box.  By searching in the xml file to find a GUI object that does what we want, we can then determine the javascript function that is called when the user interacts with that GUI object.  By finding the javascript function name, we can find the function implementation inside the ANSYS installation directory.  By finding the implementation, we can study it and figure out what it does. 

Stay tuned for the next installment to see this in action.