ACT Extension for a PID Thermostat Controller (PART 2)

(View part one of this series here.)

So, I’ve done a little of this Workbench customization stuff in a past life. My customizations involved lots of Jscript, some APDL, sweat and tears. I literally would bang my head against Eric Miller’s office door jamb wondering (sometimes out loud) what I had done to be picked as the Workbench customization guy. Copious amounts of alcohol on weeknights helped some, but honestly it still royally sucked. Because of these early childhood scars, I’ve cringed at the thought of this ACT thingy until now. I figured I’d been there, done that and I had zero, and I mean zero desire to relive any of it.

So, I resisted ACT even after multiple “suggestions” from upper management that I figure out something to do with it. That was wrong of me; I should have been quicker to given ACT a fair shot. ACT is a whole bunch better than the bad ol’ days of JScript. How is it better? Well, it has documentation… Also, there are multiple helpful folks back at Canonsburg and elsewhere that know a few things about it. This is opposed to the days when just one (brilliant) guy in India named Rajiv Rath had ever done anything of consequence with JScript. (Without him, my previous customization efforts would simply have put me in the mad house. Oh, and he happens to know a thing or two about ACT as well…)

Look Ma! My First ACT Extension!

In this post we are going to rig up the PID thermostat boundary condition as a new boundary condition type in Mechanical. In ACT jargon, this is known as adding a pre-processing feature. I’m going to refer you primarily to the training material and documentation for ACT that you can obtain from the ANSYS website on their customer portal. I strongly suggest you log on to the portal and download the training material for version 15.0 now.

Planning the Extension

When we create an ACT extension we need to lay things out on the file system in a certain manner. At a high level, there are three categories of file system data that we will use to build our extension. These types of data are:

  1. Code. This will be comprised of Python scripts and in our case APDL scripts.
  2. XML. XML files are primarily used for plumbing and for making the rest of the world aware of who we are and what we do.
  3. Resources. These files are typically images, icons, etc… that spice things up a little bit.

Any single extension will use all three of these categories of files, and so organizing this mess becomes priority number one when building the extension. Fortunately, there is a convention that ACT imposes on us to organize the files. The following image depicts the structure graphically.


We will call our extension PIDThermostat. Therefore, everywhere ExtensionName appears in the image above, we will replace that with PIDThermostat in our file structure.

Creating a UI for our Load

The beauty of ACT is that it allows us to easily create professional looking user experiences for custom loads and results. Let’s start by creating a user interface for our load that looks like the following:


As you can see in the above user interface, all of the controls and inputs for our little PID controller that we designed in Part 1 of this blog series are present. Before we discuss how we create these user elements, let’s start with a description of what they each mean.

The first item in the UI is named Heat Source/Sink Location. This UI element presents to the user a choice between picking a piece of geometry from the model and specifying a named selection. Internal to the PID controller, this location represents where in the model we will attach the control elements such that they supply or remove energy from this location. ACT provides us two large areas of functionality here. First, it provides a way to graphically pick a geometric item from the model. Second, it provides routines to query the underlying mesh associated with this piece of geometry so that we can reference the nodes or elements in our APDL code. Each of these pieces of functionality is substantial in its size and complexity, yet we get it for free with ACT.

The second control is named Temperature Monitor Location. It functions similarly to the heat source/sink location. It gives the user the ability to specify where on the model the control element should monitor, or sense, the temperature. So, our PID controller will add or remove energy from the heat sink/source location to try to keep the monitor location at the specified set point temperature.

The third control group is named Thermostat Control Properties. This group aggregates the various parameters that control the functionality of the thermostat. That is, the user is allowed to specify gain values, and also what type of control is implemented.

The forth control group is named Thermostat Setpoint Properties. This group allows the user to specify how the setpoint changes with time. An interesting ACT feature is implemented with this control group. Based on the selection that the user makes in the “Setpoint Type” dropdown, a different control is presented below for the thermostat setpoint temperature. When the user selects, “User Specified Setpoint” then a control that provides a tabular input is presented. In this case, the user can directly input a table of temperature vs time data that specifies how the setpoint changes with time. However, if the user specifies “Use Model Entity as Setpoint” then the user is presented a geometry picker similar to the controls above to select a location in the model that will define the setpoint temperature. When this option is selected, the PID controller will function more like a follower element. That is, it will try to cause the monitor location to “follow” another location in the model by adding or removing energy from the heat source/sink location. The offset value allows the user to specify a DC offset that they would like to apply to the setpoint value. Internally, this offset term will be incorporated into the constraint equation averaging method to add in the DC offset.

Finally, the last control group allows the user to visualize plots of computed information regarding the PID controller after the solution is finished. Normally this would be presented in the results branch of the tree; however, the results I would like to present for these elements don’t map cleanly to the results objects in ACT. (At least, I can’t map them cleanly in my mind…) More detail on the results will be presented below.

So, now that we know what the control UI does, let’s look at how to specify it in ACT

Specifying the UI in XML

As mentioned at the beginning, ACT relies on XML to specify the UI for controls. The following XML snippet describes the entire UI.

<extension version=“1” name=“ThermalTools”>

  <guid shortid=“thermaltools”>852acb16-4731-4e91-bd00-b464be02b361</guid>

  <script src=“” />


  <interface context=“Mechanical”>





    <toolbar name=“thermtools” caption=“Thermal Tools”>

      <entry name=“PIDThermostatLoad” icon=“ThermostatGray”

             caption=“PID Thermostat Control”>








  <simdata context=“Mechanical”>

    <load name=“pidthermostat” version=“1” caption=“PID Thermostat”

    icon=“ThermostatWhite” issupport=“false” isload=“true” color=“#0000FF”>


        <getcommands location=“solve”>writePIDThermostatLoad</getcommands>

        <getcommands location=“post”>writePIDThermostatPost</getcommands>








      <property name=“ConnectionGeo”  caption= “Heat Source/Sink Location”


        <attributes selection_filter=“vertex|edge|face” />


      <property name=“MonitorGeo”  caption= “Temperature Monitor Location”


        <attributes selection_filter=“vertex|edge|face|body” />


      <propertygroup name=“ControlProperties” caption=“Thermostat Control Properties”


        <property name=“ControlType” caption=“Control Type”

                  control=“select” default=“Both Heat Source and Sink”>

          <attributes options=“Heat Source,Heat Sink,Both Heat Source and Sink”/>


        <property name=“ProportionalGain” caption=“Proportional Gain”

                  control=“float” default=“0”/>

        <property name=“IntegralGain” caption=“Integral Gain”

                  control=“float” default=“0”/>

        <property name=“DerivativeGain” caption=“Derivative Gain”

                  control=“float” default=“0”/>


      <propertygroup name=“SetpointProperties” caption=“Thermostat Setpoint Properties”


        <propertygroup name=“SetpointType” display=“property” caption=“Setpoint Type”

                       control=“select” default=“User Specified Setpoint”>

          <attributes options=“User Specified Setpoint,Use Model Entity as Setpoint”/>

          <propertytable name=“SetPointTemp” caption=“Thermostat Set Point Temperature”

                         display=“worksheet” visibleon=“User Specified Setpoint”

                         control=“applycancel” class=“Worksheet.PropertyGroupEditor.PGEditor”>

            <property name=“Time” caption=“Time” unit=“Time” control=“float”></property>

            <property name=“SetPoint” caption=“Set Point Temperature”

                      unit=“Temperature” control=“float”></property>


          <property name=“SetpointGeo”  caption= “Setpoint Geometry”

                    visibleon=“Use Model Entity as Setpoint” control=“scoping”>

            <attributes selection_filter=“vertex|edge|face|body” />



        <property name=“SetpointOffset” caption=“Offset” control=“float” default=“0”/>


      <propertygroup name=“Results” caption=“Thermostat Results” display=“caption”>

        <property name=“ViewResults” caption=“View Results?” control=“select” default=“No”>

          <attributes options=“Yes,No”/>









Describing this in detail would take far longer than I have time for now, so I’m going to direct you to the ACT documentation. The gist of it is fairly simple though. XML provides a structured, hierarchical mechanism for describing the layout of the UI. Nested structures appear as child widgets of their parents. Callbacks are used within ACT to provide the hooks into the UI events so that we can respond to various user interactions. Beyond that, read the docs!! And, hey, before I hear any whining remember that in the old days of Jscript customization there wasn’t any documentation! When I was a Workbench Customization Kid we had to walk uphill, both ways, barefoot, in 8’ of snow for 35 miles… So shut it!

Making the Magic Happen

So, the UI is snazzy and all, but the heavy lifting really happens under the hood. Ultimately, what ACT provides us, when we are creating new BCs for ANSYS, is a clever way to insert APDL commands into the ds.dat input stream. Remember that at its core all Mechanical is, is a glorified APDL generator. I’m sure the developers love me reducing their hard labor to such mundane terms, but it is what it is… So, at the end of the day, our little ACT load objects are nothing more than miniature APDL writers. You thought we were doing something cool…

So, the magic happens when we collect up all of the input data the user specifies in our snazzy UI and turn that into APDL code that implemented the PID controller. This is obviously why I started by developing the APDL code first outside of WB. The APDL code is the true magic. Collecting up the user inputs and writing them to the ds.dat file occurs inside the getcommands callback. If you look closely at the XML code, you will notice two getcommands callbacks. The first one calls a python function named: writePIDThermostatLoad. This callback is scheduled to fire when Mechanical is finished writing all of the standard loads and boundary conditions that it implements natively and is about to write the first APDL solve command. Our commands will end up in the ds.dat file right at this location. I chose this location for the following reason. Our APDL code for the PID thermostat will be generating new element types and new nodes and elements not generated by Workbench. Sometimes workbench implements certain boundary conditions using surface effect element types. So, these native loads and boundary conditions themselves may generate new elements and element types. Workbench knows about those, because it’s generating them directly; however, it has no idea what I might be up to in my PID thermostat load. So, if it were to write additional boundary conditions after my PID load, it very well might reuse some of my element type ids, and even node/element ids. The safer thing to do is to write our APDL code so that it is robust in the presence of an unknown maximum element type/real constant set/node number/etc… Then, we insert it right before the solve command, after WB has written all of its loads and boundary conditions. Thus, the likelihood of id collisions is greatly reduced or eliminated.

Note, too, that ACT provides some utility functions to generate a new element type id and increment the internal counter within Workbench; however, I have found that these functions do not account for loads and boundary conditions. Therefore, in my testing thus far, I haven’t found them safe to use.

The second getcommands callback is setup to fire when Workbench finishes writing all of the solve commands and has moved to the post processing part of the input stream. I chose to implement a graphing functionality for displaying the relevant output data from the PID elements. Thus, I needed to retrieve this data from ANSYS after the solution is complete so that I can present it to the user. I accomplished this by writing a little bit of APDL code to enter /post26 and export all of the data I wish to plot to a CSV file. By specifying this second getcommands callback, I could instruct Workbench to insert the APDL commands after the solve completed.

Viewing the Results

Once the solution has completed, clicking on the “View Results?” dropdown and choosing “Yes” will bring up the following result viewer I implemented for the PID controller. All of the graphing functionality is provided by ACT in an import module called “chart”. This result viewer is simply implemented as a dialog with a single child control that is the ACT chart widget. This widget also allows you to layout multiple charts in a grid, as we have here. As you can see, we can display all of the relevant output data for the controls cleanly and efficiently using ACT! While this can also be accomplished in ANSYS Mechanical APDL, I think we would all agree that the results are far more pleasing visually when implemented in ACT.


Where Do We Go from Here?

Now that I’ve written an ACT module, my next steps are to clean it up and try to make it a little more production ready. Once I’m satisfied with it, I’ll publish it on this blog and on the appropriate ANSYS library. Look for more posts along the way if I uncover additional insights or gotchas with ACT programming. I will leave you with this, however. If you have put off ACT programming you really should reconsider! Being mostly new to ACT, I was able to get this little boundary condition hooked up and functioning in less than a week’s time. Given the way the user interface turned out and the flexibility thus far of the control, I’m quite pleased with that. Without the documentation and general availability of ACT, this effort would have been far more intense. So, try out ACT! You won’t be disappointed.