ANSYS ACT Customization Guide for Discovery

AIM

ANSYS, Inc. Release 2019 R3

Southpointe August 2019
2600 ANSYS Drive
Canonsburg, PA 15317 ANSYS, Inc. and
[email protected] ANSYS Europe,
Ltd. are UL
http://www.ansys.com registered ISO
(T) 724-746-3304 9001: 2015
(F) 724-514-9494 companies.
Copyright and Trademark Information

© 2019 ANSYS, Inc. Unauthorized use, distribution or duplication is prohibited.

ANSYS, ANSYS Workbench, AUTODYN, CFX, FLUENT and any and all ANSYS, Inc. brand, product, service and feature
names, logos and slogans are registered trademarks or trademarks of ANSYS, Inc. or its subsidiaries located in the
United States or other countries. ICEM CFD is a trademark used by ANSYS, Inc. under license. CFX is a trademark
of Sony Corporation in Japan. All other brand, product, service and feature names or trademarks are the property
of their respective owners. FLEXlm and FLEXnet are trademarks of Flexera Software LLC.

Disclaimer Notice

THIS ANSYS SOFTWARE PRODUCT AND PROGRAM DOCUMENTATION INCLUDE TRADE SECRETS AND ARE CONFID-
ENTIAL AND PROPRIETARY PRODUCTS OF ANSYS, INC., ITS SUBSIDIARIES, OR LICENSORS. The software products
and documentation are furnished by ANSYS, Inc., its subsidiaries, or affiliates under a software license agreement
that contains provisions concerning non-disclosure, copying, length and nature of use, compliance with exporting
laws, warranties, disclaimers, limitations of liability, and remedies, and other provisions. The software products
and documentation may be used, disclosed, transferred, or copied only in accordance with the terms and conditions
of that software license agreement.

ANSYS, Inc. and ANSYS Europe, Ltd. are UL registered ISO 9001: 2015 companies.

U.S. Government Rights

For U.S. Government users, except as specifically granted by the ANSYS, Inc. software license agreement, the use,
duplication, or disclosure by the United States Government is subject to restrictions stated in the ANSYS, Inc.
software license agreement and FAR 12.212 (for non-DOD licenses).

Third-Party Software

See the legal information in the product help files for the complete Legal Notice for ANSYS proprietary software
and third-party software. If you are unable to access the Legal Notice, contact ANSYS, Inc.

Published in the U.S.A.

Table of Contents
1. Introduction ............................................................................................................................................ 1
1.1. ACT Start Page Access ....................................................................................................................... 1
1.2. ACT App Builder Access .................................................................................................................... 2
2. AIM Wizards ............................................................................................................................................ 3
2.1. AIM Product Wizards ......................................................................................................................... 3
2.2. Custom Templates ............................................................................................................................ 4
2.3. Guided Simulations .......................................................................................................................... 5
2.3.1. Updating a Step in a Guided Simulation .................................................................................... 6
2.3.2. Closing a Guided Simulation .................................................................................................... 6
2.3.3. Understanding How Guided Simulations and Simulation Templates Differ ................................. 7
2.4. Guided Setups .................................................................................................................................. 7
2.5. Helpful Wizard Creation Information ................................................................................................. 9
2.5.1. Step Definition ......................................................................................................................... 9
2.5.1.1. Defining Step Callbacks ................................................................................................... 9
2.5.1.2. Enabling and Disabling Steps ......................................................................................... 11
2.5.1.2.1. Navigating Through Wizard Steps to Access Another Step ...................................... 12
2.5.1.2.1.1. Step Navigation Example 1 ........................................................................... 12
2.5.1.2.1.2. Step Navigation Example 2 ........................................................................... 13
2.5.1.3. Controlling Long-Running Callbacks .............................................................................. 14
2.5.1.3.1. Interrupting an Operation ..................................................................................... 15
2.5.1.3.2. Reporting Progress Information ............................................................................ 15
2.5.2. Property Definition ................................................................................................................ 15
2.5.2.1. Defining Properties ....................................................................................................... 16
2.5.2.2. Accessing Properties and Their Values ............................................................................ 16
2.5.2.3. Using Callbacks to Control Property Visibility and Validity ............................................... 18
2.5.2.3.1. Property Visibility .................................................................................................. 18
2.5.2.3.2. Property Validity ................................................................................................... 19
2.5.2.3.3. <onValidate> versus <isValid> .............................................................................. 20
2.5.2.4. Dynamically Modifying Property Options ....................................................................... 21
2.5.3. AIM Data Model ..................................................................................................................... 23
2.5.3.1. Task Representation ....................................................................................................... 23
2.5.3.1.1. Task ...................................................................................................................... 24
2.5.3.1.2. Task Component ................................................................................................... 24
2.5.3.1.3. Task Object ........................................................................................................... 25
2.5.3.1.4. Relationships Between Task Objects ...................................................................... 25
2.5.3.1.5. Task Usage Example .............................................................................................. 26
2.5.3.2. Data Model Objects ....................................................................................................... 27
2.5.3.2.1. Creating Objects ................................................................................................... 27
2.5.3.2.2. Retrieving Objects ................................................................................................ 29
2.5.3.2.3. Saving and Restoring Data for Guided Simulations ................................................. 30
2.5.4. AIM Interface Interaction ........................................................................................................ 31
2.5.4.1. Making a Given Object Visible in the Graphics Window ................................................... 32
2.5.4.1.1. Displaying the Imported Geometry ....................................................................... 32
2.5.4.1.2. Displaying a Physics-related Object ....................................................................... 32
2.5.4.1.3. Displaying a Computed Result ............................................................................... 32
2.5.4.2. Saving the Image in the Graphics Window to a File ......................................................... 34
2.5.4.3. Setting the Selection Filter to a Specific Topological Entity .............................................. 34
2.5.4.4. Controlling the Visibility for Topological Entities ............................................................. 34
2.5.4.5. Associating Geometry Information with Your Extension .................................................. 35
2.5.5. Miscellaneous Wizard-Related Information ............................................................................. 36

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. iii
ACT Customization Guide for Discovery AIM

2.5.5.1. Providing Custom Wizard Help ....................................................................................... 36

2.5.5.2. Setting Script Versions ................................................................................................... 37
2.6. Custom Template Examples ............................................................................................................ 37
2.6.1. Custom Template (Single-Step) ............................................................................................... 38
2.6.1.1. Creating the Single-Step Custom Template ..................................................................... 38
2.6.1.2. Defining Functions for the Single-Step Custom Template ............................................... 39
2.6.2. Custom Template (Multiple-Step) ............................................................................................ 41
2.6.2.1. Creating the Multiple-Step Custom Template ................................................................. 41
2.6.2.2. Defining Functions for the Multiple-Step Custom Template ............................................ 43
2.7. Guided Simulation Example ............................................................................................................ 45
2.7.1. Creating the Guided Simulation .............................................................................................. 46
2.7.2. Defining Functions for the Guided Simulation ......................................................................... 47
2.8. AIM Project Wizards ........................................................................................................................ 51
2.8.1. Creating the AIM Project Wizard ............................................................................................. 51
2.8.2. Defining Functions for the AIM Project Wizard ........................................................................ 53
2.8.3. Reviewing AIM Project Wizard Results ..................................................................................... 55

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
iv of ANSYS, Inc. and its subsidiaries and affiliates.
Chapter 1: Introduction
This guide assumes that you are familiar with the general ACT usage information in the ACT Developer's
Guide. This section supplies ACT usage information specific to AIM:
1.1. ACT Start Page Access
1.2. ACT App Builder Access

AIM Wizards (p. 3) describes AIM project wizards and target product wizards, which create custom
templates, guided simulations, and guided setups.

Note

• While ACT extensions for AIM support custom boundary conditions for Fluent solvers, they
do not support them for non-Fluent solvers. If you need to use custom boundary conditions
alongside the MAPDL solver, you must use ANSYS Mechanical instead of AIM.

• For information on all ACT API changes and known issues and limitations that may affect
your existing ACT extensions, see Migration Notes and Known Issues and Limitations in the
ANSYS ACT Developer's Guide.

1.1. ACT Start Page Access

From an AIM project or study, you access the ACT Start Page by clicking the home button and then
selecting Extensions → ACT Start Page.

AIM's Extensions menu provides options for accessing many ACT tools, which are also accessible from
the ACT Start Page itself. Once accessed, the ACT Start Page and all ACT tools are used as described
in the ANSYS ACT Developer's Guide.

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 1
Introduction

1.2. ACT App Builder Access

From AIM, you can access the ACT App Builder by doing any one of the following:

• From the AIM start page, in the upper right corner, click the button with the three vertical dots and
then select Open App Builder.

• From an AIM project or study, click the home button and then select Extensions → Open App
Builder.

You can also access the ACT App Builder from the ACT Start Page by clicking the Open App Builder
button.

Once started, the ACT App Builder is used to create ACT extensions, or apps, in a visual environment
as described in the ANSYS ACT Developer's Guide.

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
2 of ANSYS, Inc. and its subsidiaries and affiliates.
Chapter 2: AIM Wizards
You can use ACT to create project wizards and target product wizards for AIM.

• Project wizards for AIM are executed from AIM's Project tab. Because they sit on top of AIM rather than
being integrated within AIM, project wizards are rarely used in AIM. Consequently, coverage on project
wizards is provided at the end of this section. For more information, see AIM Project Wizards (p. 51).

• Target product wizards for AIM are implemented and executed as custom templates, guided simulations,
and guided setups.

The following sections provide wizard creation information and examples:

2.1. AIM Product Wizards
2.2. Custom Templates
2.3. Guided Simulations
2.4. Guided Setups
2.5. Helpful Wizard Creation Information
2.6. Custom Template Examples
2.7. Guided Simulation Example
2.8. AIM Project Wizards

Note

The Extension Manager is available in AIM so that you can install and load ACT extensions
that contain AIM wizards.

2.1. AIM Product Wizards

To create a target product wizard for AIM, in the extension's XML file, you add the element <wizard>
and set the attribute context to Study. You then use the attributes persistent and subcontext
to define whether the wizard is to be implemented as a custom template, guided simulation, or guided
setup.

Simulation Type Persistent Attribute Subcontext Attribute

Custom template Unspecified Unspecified
Guided simulation Specified Unspecified
Guided setup Unspecified Specified

The custom templates and guided simulations that you have installed and loaded in AIM are available
on AIM's start page. A guided simulation has the following icon on the bottom left of its tile to differ-
entiate it from a custom template:

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 3
AIM Wizards

The guided setups that you have installed and loaded in AIM appear in the Guide Me context (right-
click) menu when a compatible object and geometry entity are selected. The Guide Me menu is present
only if the object and geometry selection to which you’ve navigated matches the object or task and
geometry selection defined in the extension.

2.2. Custom Templates

A custom template automates the definition of an AIM simulation process, prompting you for needed
inputs. In the extension's XML file, for the element <wizard>, both the attributes persistent and
subcontext are unspecified by default. In this case, the extension is implemented as a custom template.

All custom templates that are installed and loaded in AIM are available on the start page. The following
figure displays both property-level and step-level help for the ANSYS- installed Structural template.

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
4 of ANSYS, Inc. and its subsidiaries and affiliates.
 Guided Simulations

If you have created help for a custom template, the following occurs when the custom template is ex-
ecuted:

• Step-level help is shown in AIM's context-sensitive help panel. A double arrow icon switches between hiding
and displaying the panel. When the step-level panel is hidden, you can also click the question mark icon in
the step's header to display it.

Note

After moving to a different step, you must click the question mark icon in the header of
the step to refresh the step-level help panel with the appropriate content.

• Property-level help is shown only when you click the question mark icon that appears when you place the
mouse cursor over a property.

Extension examples for custom templates are supplied. For more information, see Custom Template
Examples (p. 37).

2.3. Guided Simulations

A guided simulation displays your own end-to-end custom workflow in a persisted view, remaining
open until you close it. In the extension's XML file, for the element <wizard>, you set the attribute
persistent to true to create a guided simulation. All guided simulations that have been installed
and loaded in AIM are available on the start page.

When you start a guided simulation, the view panel immediately displays a Guided Simulation tab
with all steps in the workflow. You do not have to complete the steps in a guided simulation sequentially.

Clicking any step in the Guided Simulation tab makes the step active in the data panel. Using this tab,
you can navigate to the various steps, supplying appropriate data and updating as necessary.

You can view the state of the active step in the data panel. You can view the states of all steps in the
Guided Simulation tab. If a step is disabled during execution, it is removed from this tab.

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 5
AIM Wizards

The following topics provide additional information about guided simulations:

2.3.1. Updating a Step in a Guided Simulation
2.3.2. Closing a Guided Simulation
2.3.3. Understanding How Guided Simulations and Simulation Templates Differ

An extension example for a guided simulation is supplied. For more information, see Guided Simulation
Example (p. 45).

2.3.1. Updating a Step in a Guided Simulation

In the data panel, the visual indications that can be shown for the state of a step are a subset of those
shown for AIM tasks. A step can be in one of three states:

The Attention required state is tied to the current callback <isValid> to determine if the data
supplied for the step is valid. A step in this state has one or more fields that require your attention
before the step can be updated. The step cannot be updated if any previous step requires attention.

The Up-to-date state indicates that the callback <onUpdate> for the step has been executed and
that no change was made to this step or any previous step.

The Out-of-date state indicates that the step has been modified after an update and an update is
once again required. An up-to-date step becomes out-of-date if the data for a previous step is changed.

When an out-of-date step is active in the data panel, you click either the update icon or Update
button to execute the callback <onUpdate> for the step. Both the icon and button are blue when
the step requires an update. In a guided simulation, the update of a step invokes the callback
<onUpdate> for all previous steps that need to be updated.

Unlike a simulation template, a guided simulation is not dismissed when the last step is executed.
Unless you close a guided simulation, you can go back to any step and make changes and update
multiple times.

2.3.2. Closing a Guided Simulation

In principle, users of a guided simulation leave it running because they do not need to interact directly
with AIM. However, a user can close a simulation by clicking Close on any step in the data panel.

Currently, only one guided simulation or simulation template can be open at a time. If you attempt
to start another, a dialog box opens, indicating the name of the one that is already running. You can
choose to either close the running instance or let it remain running.

If you choose to close a guided simulation and then start it again later, the last created data is restored.

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
6 of ANSYS, Inc. and its subsidiaries and affiliates.
 Guided Setups

2.3.3. Understanding How Guided Simulations and Simulation Templates

Differ
A summary follows of the key distinctions between guided simulations and simulation templates.

• Data supplied in a guided simulation is persisted, which is not the case for a simulation template. Each
time you start a simulation template, a new instance is opened, which means that no previously created
data is restored. Each time you start a guided simulation, the same instance is opened, even after
closing and then resuming a project. Because your choices are saved with the project, AIM always
populates the guided simulation with your last choices.

• A guided simulation uses the Next and Back buttons in the data panel only for navigation through
the steps. These buttons are not tied to the execution of callbacks as they are in a simulation template.
Because the steps in a guided simulation do not have to be completed sequentially, you can navigate
to any step, regardless of its state.

• Each step in a guided simulation has Close and Update buttons.

– If you click Close, a dialog box opens, asking you to confirm that you want to close the guided
simulation. Because steps in a guided simulation do not have to be completed sequentially, the last
step does not have a Finish button.

– When you click the update icon or Update button for an out-of-date step in the data panel, the
callback <onUpdate> for the step is invoked. When the update of a step is invoked, the callback
<onUpdate> for any previous step that is out-of-date is executed before the update of the current
step. If any previous step requires attention, the Update button is not shown.

• In the Guided Simulation tab in the view panel, each step has a context menu with a command for
executing the callback <onUpdate>. If the callback <IsReset> is implemented for the step, the
context menu also includes a command for resetting the step. However, the reset of a step does not
invoke the callback <IsReset> for previous steps.

• When you start working on a guided simulation, the Workflow tab in the view panel disappears.

2.4. Guided Setups

In the extension's XML file, for the element <wizard>, the attribute subcontext specifies if the
simulation is a guided setup. Installed and loaded guided setups appear in the Guide Me context (right-
click) menu when a compatible object and geometry entity are selected. Various examples follow of
what you can enter for a guided setup named Test1. For the attribute subcontext, you specify a
task, task group, or object. For more information, see AIM Data Model (p. 23).

To see the internal name of a task, task group, or object, you place the mouse cursor in the upper left
corner of the data panel. The resulting tooltip displays this information. In the following figure, the
tooltip shows the task group has an internal name of Physics Solution

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 7
AIM Wizards

Example 1
<wizard name="Test1" caption = "Test1" version="1" context="Study" subcontext = "Physics Solution/Face" icon="Term

When AIM is displaying a task group of type Physics Solution, the template is shown in the Guide
Me context menu for the selected face.

Example 2
<wizard name="Test1" caption = "Test1" version="1" context="Study" subcontext = "Support/Face" icon="Terminal" per

When AIM is displaying an object of type Support, the template is shown in the Guide Me context
menu for the selected face.

Example 3
<wizard name="Test1" caption = "Test1" version="1" context="Study" subcontext = "Face" icon="Terminal" persistent=

Regardless of the type of task, task group, or object that AIM is displaying, the template is shown in
the Guide Me context menu for the selected face.

Example 4
<wizard name="Test1" caption = "Test1" version="1" context="Study" subcontext = "Meshing" icon="Terminal" persiste

The template is shown in the Guide Me content menu for the selected meshing task.

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
8 of ANSYS, Inc. and its subsidiaries and affiliates.
 Helpful Wizard Creation Information

Summary
As you can see by the first two code examples, a forward slash (/) in the attribute subcontext identifies
a task, task group, or object before the slash and an object type after the slash. Object types include
Vertex, Edge, Face, and Body.

The second and third code examples demonstrate how you can enter a string for matching only a
particular type of task, task group, or object.

2.5. Helpful Wizard Creation Information

The following topics supply information helpful to creating AIM wizards:
2.5.1. Step Definition
2.5.2. Property Definition
2.5.3. AIM Data Model
2.5.4. AIM Interface Interaction
2.5.5. Miscellaneous Wizard-Related Information

2.5.1. Step Definition

AIM custom templates and guided simulations are ACT extensions that contain AIM target product
wizards. In the wizard, you define a series of steps to create a custom workflow. Within each step, you
define step-specific properties and callbacks.

The following topics provides AIM-specific information about defining step callbacks:
2.5.1.1. Defining Step Callbacks
2.5.1.2. Enabling and Disabling Steps
2.5.1.3. Controlling Long-Running Callbacks

For information on defining properties and their callbacks, see Property Definition (p. 15). For general
information about wizard creation, see Simulation Wizards in the ANSYS ACT Developer’s Guide.

2.5.1.1. Defining Step Callbacks

The following XML codes defines the callbacks most commonly used in a step definition:
<step name="Step1" caption="Step 1" version="1">
<callbacks>
<oninit>stepInit</oninit>
<onrefresh>stepRefresh</onrefresh>
<onupdate>stepUpdate</onupdate>
<oncreate>stepFirstUpdate</oncreate>
<onreset>stepReset</onreset>
</callbacks>
</step>

• The callback <oninit> is invoked when the custom template or guided simulation is started. This
callback should include commands that need to be executed only once to initialize the step.

• The callback <onrefresh> is invoked every time that the step is visited, before displaying the step
properties in AIM. For example, this callback can contain actions that change or refresh some property
options. This is necessary if the options depend on properties of other steps that might have changed
after the step was visited.

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 9
AIM Wizards

• The callback <onupdate> is used to perform actions that bring the step to an up-to-date state. This
action is invoked differently in guided simulations versus custom templates.

– For guided simulations, the Update button is available where the step properties appear. Addition-
ally, in the step representation of the workflow, the right-click menu provides an Update option.
If any step upstream of the given step is out-of-date, the step’s callback <onupdate> executes
the update of out-of-date steps that are upstream before executing its own update. The Update
option is disabled if the step state is already up-to-date or if the state of the step, or any upstream
step, is Attention Required.

– For custom templates, there is no display of step state and no button for invoking the update. In-
stead, the callback <onupdate> is executed when you click Next to navigate to the next step.
The Next button is disabled when any step property is in an invalid state. If you navigate through
the steps, you must make sure that the callback <onupdate> does not execute any duplicate
action.

Each step in a custom template or a guided simulation must define the callback <onupdate>.
You should define an empty callback for steps that do not perform any action.

• The callback <oncreate> is relevant only to guided simulations. If defined, it is used the first time
that a step is updated. Subsequent updates of the step invoke the callback <onupdate>. Typically
the first time that you initiate a step update, you must create the AIM objects for the step’s properties
in the IronPython script. This is the purpose of the callback <oncreate>. After the first update, you
must update object properties but not create new properties. This is the purpose of the callback
<onupdate>. You should also know that when you close and reopen a guided simulation, AIM
keeps track of whether an update was previously executed. Consequently, once the callback <oncre-
ate> is invoked, it is not invoked again. Again, the callback <oncreate> is invoked only on the
first update. The callback <onupdate> is invoked for every other update.

• The callback <onreset> is typically used to remove AIM data created in another callback. This action
is invoked differently in guided simulations versus custom templates.

– For guided simulations, the callback <onreset> can be invoked by right-clicking the step repres-
entation of the workflow and selecting Reset. This option is visible only if the callback <onreset>
has been defined in the XML file.

– For custom templates, the callback <onreset> is invoked when Back is clicked. The step must
define this callback for the Back button to display. If it is not defined, a Cancel button displays in-
stead. Clicking Cancel terminates the template execution. Although the callback <onreset>
must be defined to enable navigating back to the previous step, you can define an empty callback
if you don’t want the data for this previous step to be deleted when Back is clicked. As noted
earlier, clicking Next invokes an update. Consequently, you must ensure that no duplicate action
is executed if the callback <onreset> does not delete the data.

The following code samples provide a simple example of using the callbacks <oncreate> (first update
and object creation), <onupdate> (update of existing object properties), and <onreset> (deletion
of objects).

XML Definition
<step name="Inlet1" caption = "Inlet definition" version = "1" icon = "cht-header">
<description></description>
<property name="Location" caption="Inlet location" control="scoping" >
</property>
<property name = "VelocityMagnitude" caption = "Velocity Magnitude" control="float" unit="Velocity">

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
10 of ANSYS, Inc. and its subsidiaries and affiliates.
 Helpful Wizard Creation Information

</property>
<callbacks>
<oncreate>stepFirstUpdate</oncreate>
<onupdate>stepUpdate</onupdate>
<onreset>stepReset</onreset>
</callbacks>
</step>

IronPython Function Definition

def onFirstUpdate(step):
system1 = GetSystem(Name="Study")
study1 = system1.GetContainer(ComponentName="Study")
inletLocation = inletStep.Properties["Location"].Value.LocationSet.JournalStrings
inletPysicsRegion = getPhysicsRegionFromBoundaryLocation(inletLocation)
#Create an entity of type Inlet and store its name in the step attributes
inletCondition = study1.CreateEntity(Type="InletBoundary", Association=inletPr)
inletStep.Attributes["inletName"] = inletCondition.Name
#Assign properties
inletCondition.Location = inletLocation
inletCondition.Flow.Option = "Velocity"
inletCondition.Flow.Velocity.Magnitude = inletStep.Properties["VelocityMagnitude"].Value

def stepUpdate(step):
system1 = GetSystem(Name="Study")
study1 = system1.GetContainer(ComponentName="Study")
#Retrieves the inlet name from the step attributes
inletName = inletStep.Properties.Attributes["inletName"]
#Retrieves the object by its name
inletCondition = study1.GetBoundary(Name=inletName)
#Assign properties
inletCondition.Location = inletLocation
inletCondition.Flow.Option = "Velocity"
inletCondition.Flow.Velocity.Magnitude = inletStep.Properties["VelocityMagnitude"].Value

def stepReset(step):
system1 = GetSystem(Name="Study")
study1 = system1.GetContainer(ComponentName="Study")
#Retrieves the inlet name from the step attributes
inletName = inletStep.Properties.Attributes["inletName"]
#Retrieves the object by its name
inletCondition = study1.GetBoundary(Name=inletName)
#Delete Object
Study.Delete(Items=[inletCondition1])

2.5.1.2. Enabling and Disabling Steps

Custom templates and guided simulations are used to create custom workflows in AIM. The ability
to dynamically enable and disable steps greatly increases the flexibility of your custom extension.
Depending on which steps are enabled, different workflows can be executed.

All steps are enabled by default. To disable a step, in the XML file, you must set the attribute enabled
to false:
<step name="Step1" caption="Step 1" version="1" enabled="false">

While the step definition specifies whether a step is displayed initially, workflow flexibility is achieved
by dynamically changing this setting in a function definition. You can achieve this in any callback for
a step or a property by setting step.IsEnabled to True or False:
def mycallback(step, prop):
step.IsEnabled = False

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 11
AIM Wizards

2.5.1.2.1. Navigating Through Wizard Steps to Access Another Step

In practical cases, a callback needs to enable or disable steps that are downstream (or less frequently
upstream) of the step for which the callback is invoked. The following function definition shows how
to navigate through wizard steps to access another step:
def updateCallBack(step, prop):
nextStep = step.NextStep #returns None if step is the last step
nextEnabledStep = step.NextEnabledStep #returns None if step is the last enabled step
previousStep = step.PreviousStep #returns None if step is the first step
previousEnabledStep = step.previousEnabledStep #returns None if step is the first enabled step
allSteps = step.Wizard.Steps
#to iterate on the steps
for step in allSteps:
#addCondition here
step.IsEnabled = False

You can also access a specific step by name using the function getStepByName, which is described
in Accessing Properties and Their Values (p. 16).

2.5.1.2.1.1. Step Navigation Example 1

This very simple example defines two Boolean properties in Step 1, which control the visibility of
the two subsequent steps (Step 2 and Step 3). The disabling or enabling of Step 2 and Step
3 is performed as part of the callback <onupdate> for Step 1.

XML Definition
<step name="Step1" caption="Step 1" version="1">
<property name="DisableStep2" caption="Disable Step 2" control="boolean" default = "false"/>
<property name="DisableStep3" caption="Disable Step 3" control="boolean" default = "false"/>
<callbacks>
<onupdate>updateStep1</onupdate>
</callbacks>
</step>

<step name="Step2" caption="Step 2" version="1">

<property name="Step2Description" caption="Step 2 Description" control="string" default = "this step is onl
<callbacks>
<onupdate>emptyUpdate</onupdate>
</callbacks>
</step>

<step name="Step3" caption="Step 3" version="1">

<property name="Step3Description" caption="Step 3 Description" control="string" default = "this step is onl
<callbacks>
<onupdate>emptyUpdate</onupdate>
</callbacks>
</step>

IronPython Function Definition

def updateStep1(step):
disableStep2 = bool(step.Properties["DisableStep2"])
disableStep3 = bool(step.Properties["DisableStep3"])
step2 = step.NextStep
step2.IsEnabled = True if disableStep2 == False else False
step3 = step2.NextStep
step3.IsEnabled = True if disableStep3 == False else False

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
12 of ANSYS, Inc. and its subsidiaries and affiliates.
 Helpful Wizard Creation Information

2.5.1.2.1.2. Step Navigation Example 2

This more complex example goes through a number of identical steps, such as steps that each define
a given boundary condition. You use such code when you don’t know beforehand how many steps
will be necessary. While dynamic addition of steps is currently not possible, you can use step disabling
to achieve this objective.

Consider a workflow that allows you to define a variable number of inlet boundary conditions. You
must choose the maximum number allowed and then provide definitions for all of these steps in
the XML file.

In the first step, you define a property in which you can dynamically choose the number of inlets,
up to the maximum number allowed. This information is used to decide which of the following steps
to disable.

XML Definition
<step name="Inlet1" caption = "Inlet definition" version = "1" icon = "cht-header">
<description></description>
<property name="NumberOfInlets" caption="Number of inlets" control="select" default="1">
<attributes options="1,2,3,4,5" />
<callbacks>
<onvalidate>validateNumberOfInlets</onvalidate>
</callbacks>
</property>
<property name="Location" caption="Inlet location" control="scoping" >
</property>
<property name = "VelocityMagnitude" caption = "Velocity Magnitude" control="float" unit="Velocity">
</property>
<callbacks>
<onrefresh>refreshNumberOfInlets</onrefresh>
<oncreate>stepFirstUpdate</oncreate>
<onupdate>stepUpdate</onupdate>
<onreset>stepReset</onreset>
</callbacks>
</step>

<step name="Inlet2" caption = "Inlet 2 definition" version = "1" icon = "cht-header">

<description></description>
<property name="Location" caption="Inlet location" control="scoping" >
</property>
<property name = "VelocityMagnitude" caption = "Velocity Magnitude" control="float" unit="Velocity">
</property>
<callbacks>
<onrefresh>refreshNumberOfInlets</onrefresh>
<oncreate>stepFirstUpdate</oncreate>
<onupdate>stepUpdate</onupdate>
<onreset>stepReset</onreset>
</callbacks>
</step>

<step name="Inlet3" caption = "Inlet 3 definition" version = "1" icon = "cht-header">

<description></description>
<property name="Location" caption="Inlet location" control="scoping" >
</property>
<property name = "VelocityMagnitude" caption = "Velocity Magnitude" control="float" unit="Velocity">
</property>
<callbacks>
<onrefresh>refreshNumberOfInlets</onrefresh>
<oncreate>stepFirstUpdate</oncreate>
<onupdate>stepUpdate</onupdate>
<onreset>stepReset</onreset>
</callbacks>
</step>

<step name="Inlet4" caption = "Inlet 4 definition" version = "1" icon = "cht-header">

<description></description>

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 13
AIM Wizards

<property name="Location" caption="Inlet location" control="scoping" >

</property>
<property name = "VelocityMagnitude" caption = "Velocity Magnitude" control="float" unit="Velocity">
</property>
<callbacks>
<onrefresh>refreshNumberOfInlets</onrefresh>
<oncreate>stepFirstUpdate</oncreate>
<onupdate>stepUpdate</onupdate>
<onreset>stepReset</onreset>
</callbacks>
</step>

<step name="Inlet5" caption = "Inlet 5 definition" version = "1" icon = "cht-header">

<description></description>
<property name="Location" caption="Inlet location" control="scoping" >
</property>
<property name = "VelocityMagnitude" caption = "Velocity Magnitude" control="float" unit="Velocity">
</property>
<callbacks>
<oninit>initializeNumberOfInlets</oninit>
<oncreate>stepFirstUpdate</oncreate>
<onupdate>stepUpdate</onupdate>
<onreset>stepReset</onreset>
</callbacks>
</step>

Disabling of steps occurs in two callbacks:

• The callback <oninit> when the page is first visited to display the number of steps corresponding
to the initial (default) value

• The callback <onvalidate> for the property NumberOfInlets, where you set the desired
number of inlets

IronPython Function Definition

def validateNumberOfInlets(step, prop):
numberOfInlets = int(prop.Value)
disableSteps(step, numberOfInlets)

def initializeNumberOfInlets(step):
numberOfInlets = int(step.Properties["NumberOfInlets"].Value)
disableSteps(step, numberOfInlets)

def disableSteps(step, numberOfActiveSteps):

s = step.NextStep
for i in range(2,6): # we have defined a maximum of 5 inlet steps
if s == None:
break
s.IsEnabled = True
if i > numberOfActiveSteps:
s.IsEnabled = False
s = s.NextStep

2.5.1.3. Controlling Long-Running Callbacks

Generally, the execution of callbacks is not time-consuming. However, the execution of the callback
<onupdate> can be long-running, especially if it invokes the update of an underlying mesh or
physics task.

For such a case, you might want to have some level of control on the long-running operation, such
as being able to:

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
14 of ANSYS, Inc. and its subsidiaries and affiliates.
 Helpful Wizard Creation Information

• Interrupt the operation when the solution is not converging or you want to adjust the values of some
properties

• Present information about the progress of the operation

2.5.1.3.1. Interrupting an Operation

To allow the callback <onupdate> to be interrupted, in the callback definition, you must set the
attribute caninterrupt to true:
<callbacks><onupdate>updateCallback caninterrupt="true"</onupdate></callbacks>

When the callback <onupdate> specifies that it can be interrupted, AIM displays the interrupt icon.
When you click this icon, AIM ends the execution as soon as the next stopping point is reached. The
exact point at which the execution stops depends on the underlying operation that is being executed.
For example, the stopping point could be after execution of an iteration for a fluid solver or after
the update for a task. If no good stopping point is found, the execution continues until completion.

Specifying that an update can be interrupted prevents AIM from journaling the actions that are ex-
ecuted in the update callback. If you want actions to be recorded in a journal, you should not set
the attribute caninterrupt to true.

2.5.1.3.2. Reporting Progress Information

You can display progress information in AIM by including step.UpdateProgressInforma-
tion(value) in the function definition for the update callback. For each portion of the update,
you specify a number between 0 and 100 to display in the progress bar. The progress is considered
complete when the sum of the specified values for each portion reaches 100.
def updateCallback(step):
#task creation commands (10% of the time)
.....
step.UpdateProgressInformation(10)
#mesh creation (25% of the time)
....

step.UpdateProgressInformation(25)
#Solve execution (60% of the time)
...

step.UpdateProgressInformation(65)
#Results evaluation (5% of the time)
.....

step.UpdateProgressInformation(5)

Setting a value of 100 before the completion of the update results in inaccurate information being
displayed in the progress bar. However, such an action has no effect on the actual completion of
the update callback.

2.5.2. Property Definition

Defining properties and their callbacks is a significant part of the work involved with creating extensions.
The following topics provide a summary of the definition process and explain how to access and
modify properties and their values:
2.5.2.1. Defining Properties
2.5.2.2. Accessing Properties and Their Values

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 15
AIM Wizards

2.5.2.3. Using Callbacks to Control Property Visibility and Validity

2.5.2.4. Dynamically Modifying Property Options

2.5.2.1. Defining Properties

In a property definition, the attribute control specifies the property type, and the attribute default
specifies the default value. Guidelines follow for defining properties:

• For a Boolean property, you must provide a default value for the property for it to display in AIM.

• For all other property types, AIM displays the error message Input required if you do not provide a
default value, even when leaving the default blank is a legitimate choice. You must enter a value to
make the property valid.

• For a multi-select property, if you do not want a default value selected, you must include de-
fault=“” in the property definition. Setting the attribute default to an empty string value ensures
that Input required is not shown.

• For a float property, if a unit is specified, the default value should be a string in the form "value [
unit ]".

The following XML code shows definitions for several properties:

<step name="Step1" caption="Step 1" version="1">
<property name="IntProp" caption="Integer property" control="integer" default = "1"/>
<property name="RealProp" caption="Real property" control="float" default = "1.0 [m s^-1]" unit="Velocit
<property name="BoolProp" caption="Boolean Property" control="boolean" default="False"/>
<property name="ScopingProp" caption="Scoping property" control="scoping" />
<property name="MultiSelectProp" caption="Multi Select Property" control="multiselect" default="Option A
<attributes options="Option A,Option B,Option C" />
</property>
<property name="SelectProp" caption="Single Select Property" control="select", default="Option A" >
<attributes options="Option A,Option B,Option C" />
</property>
</step>

2.5.2.2. Accessing Properties and Their Values

In an extension’s XML file, the callbacks defined for a property have access to the property and to
step information. The other properties defined in the step can be accessed via the dictionary
step.Properties, whose keys are the names of the properties defined in the XML file.

You can also use the call step.Properties to access properties from a step-specific callback, such
as an update, that is passed only the step information.

In the XML code in the previous topic, callbacks invoke the following property definitions in the
IronPython script:
def myPropertyCallback(step, prop):
value = prop.Value # returns "Option A"
properties = step.Properties
intProp = properties["IntProp"]

def myUpdateCallback():
properties = step.Properties
boolProp = properties["BoolProp"]

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
16 of ANSYS, Inc. and its subsidiaries and affiliates.
 Helpful Wizard Creation Information

In some cases, it is possible that a callback for a step or a property within a step must access inform-
ation about properties in a different step. Using the utility function getStepByName, you can access
a step by specifying the step name that is defined in the XML file:
def getStepByName(currentStep, stepName):
for step in currentStep.Wizard.Steps:
if step.Key == stepName:
return step.Value
return None

For example, you can access the properties for a step within the update callback of a different step:
def updateStep():
properties = step.Properties
step2 = getStepByName(step, "Step2")
step2Properties = step2.Properties

To access the value of a property, you use prop.Value. The type returned by prop.Value is often,
but not always, a string that can be converted to a different variable type if needed:
def updateStep(step, prop):
properties = step.Properties
intProp = properties["IntProp"]
intPropValue = int(intProp.Value) #returns 1
boolProp = properties["BoolProp"]
boolPropValue = bool(boolProp.Value) #returns False

Float Properties
For a float property:

• prop.Value returns a float value that contains the value of the property without need of conversion.

• prop.UnitString returns the unit in which the property is defined.

• prop.ValueString returns a string that contains the float value and the unit in which the property
is defined.

Sample code follows for a float property:

def updateStep(step, prop):
properties = step.Properties
realProp = properties["RealProp"]
value = realProp.Value #returns 1.0 - no need to cast
unitString = realProp.UnitString # returns "m s^-1"
valueString = realProp.ValueString #returns "1.0 [m s^-1]"

Select or Multi-Select Properties

For a select or multi-select property, prop.Value returns the values corresponding to the user se-
lection.

• For a select property, prop.Value is a string that contains the single value selected.

• For a multi-select property, prop.Value is a list that contains one or more values selected.

Sample code follows for both a select property and multi-select property:

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 17
AIM Wizards

def updateStep(step, prop):

properties = step.Properties
multiSelectProp= properties["MultiSelectProp"]
multiSelectPropValue = multiSelectProp.Value #returns ["Option A", "Option B"]
selectProp= properties["SelectProp"]
selectPropValue = selectProp.Value #returns "Option A"

Scoping Properties
For a scoping property, prop.Value can be used to access LocationSet, which defines the field
JournalString. This field contains the string identifiers for the entities that have been associated
with the scoping property.

Sample code follows for a scoping property:

def updateStep(step, prop):
properties = step.Properties
scopingProp = properties["ScopingProp"]
locationSelected = scopingProp.Value.LocationSet.JournalStrings #returns a list containing identifiers for t

2.5.2.3. Using Callbacks to Control Property Visibility and Validity

The following topics describes the use of the callbacks <isVisible>, <isValid>, and <onVal-
idate>, which are used to control the validity and visibility of a property.
2.5.2.3.1. Property Visibility
2.5.2.3.2. Property Validity
2.5.2.3.3. <onValidate> versus <isValid>

2.5.2.3.1. Property Visibility

In the XML file, you use the callback <isVisible> to control the visibility of a property. When the
callback returns False, AIM does not display the property. For guided simulations, AIM ignores in-
visible properties in the computation of the step state.

In the following definition, the visibility of the property InletVelocity is based on the value of
the property FlowSpecification, which specifies the type of boundary condition to apply to a
given location.

XML Definition
<property name="FlowSpecification" caption="Flow specification" control="select" default="Velocity">
<attributes readonly-options="" options = "Velocity,Pressure,Mass flow"/>
</property>
<property name = "VelocityMagnitude" caption = "Velocity Magnitude" control="float" unit="Velocity">
<callbacks>
<isVisible>isVelocityVisible</isVisible>
</callbacks>
</property>

IronPython Function Definition

def isVelocityVisible(step, prop):
flowSpecification = step.Properties["FlowSpecification"].Value
return flowSpecification == "Velocity"

The XML definition assumes that the properties FlowSpecification and VelocityMagnitude
are defined in the same step. The callback obtains the value of the property FlowSpecification

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
18 of ANSYS, Inc. and its subsidiaries and affiliates.
 Helpful Wizard Creation Information

from the IronPython script and then checks its value to determine the visibility of the property Ve-
locityMagnitude.

In a more complex scenario, you can specify the visibility of a property by the value of the property
defined in a different step. Two options are possible:

• Use a global variable to store the value of the property that determines visibility. You must define
the global variable in another callback before its use:
def isVelocityVisible(step, prop):
global flowSpecification
return flowSpecification == "Velocity"

• Access the step where the property FlowSpecification is defined and obtain the property
value. To accomplish this, you use the utility function getStepByName, which is described in the
previous topic, to retrieve the property and its value:
def isVelocityVisible(step, prop):
specificationStep = getStepByname(step, "SpeficationStep")
flowSpecification = specificationStep.Properties["FlowSpecification"].Value
return flowSpecification == "Velocity"

Note

The use of global variables is often a quick solution that works well for wizards used
as AIM custom templates. However, for guided simulations, the use of global variables
is discouraged because global variables are no longer defined when a guided simu-
lation is closed and reopened in a different session.

2.5.2.3.2. Property Validity

In the XML file, you can use the callback <isValid> to determine whether the user input for a
property is valid. The update callback is disabled for a given step if one or more properties are invalid.

You might use this callback to:

• Flag an error in the value of the property

• Display an error message if the property value is invalid

• Display an informational message, regardless of whether the property value is valid

• Determine whether a property is valid depending upon dynamic manipulation of property options

The following code samples show how the callback can flag an error or display a message when
validating a property.

XML Definition
<property name="Bodies" caption="Bodies forming fluid region 1" control="scoping" >
<callbacks>
<isValid>isBodySelectionValid</isValid>
</callbacks>
</property>

IronPython Function Definition 1

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 19
AIM Wizards

In this function definition, the callback <isValid> validates whether the value selected for a
scoping control corresponds to an entity of type Body. If the selection corresponds to a different
type, an error message displays for the property, and the property is marked as invalid.
def isBodySelectionValid(step, prop):
if step.Properties["Bodies"].Value == None:
return False
locationSet = step.Properties["Bodies"].Value.LocationSet
model = Study.GetCurrentModelForExtension()
selectionTypes = Study.GetGeometryReferenceTypes(LocationSet = locationSet, Model = model)
if len(selectionTypes) > 1 or str(selectionTypes[0]).find("Body") < 0:
prop.StateMessage = "Invalid selection"
return False
return True

IronPython Function Definition 2

In this function definition, the callback <isValid> validates a custom property that represents a
material. If Unknown is selected, a warning message displays, indicating that additional steps must
be taken in AIM.
def isMaterialValid(step, prop):
prop.StateMessage = ""
if prop.Value == "Unknown":
prop.StateMessageType = StateMessageTypes.Information
prop.StateMessage = "You will need to visit the Material Assignments page to select the material."
if prop.Value == "":
prop.StateMessageType = StateMessageTypes.Error
prop.StateMessage = "Input required"
return False
return True

Note

AIM provides a built-in check when the value of a property is undefined. However,
a callback must implement a check if it overrides the built-in validation.

2.5.2.3.3. <onValidate> versus <isValid>

For a given property, the callback <onValidate> is invoked whenever the value of the property
is modified. The callback <isValid> is invoked more broadly because it determines whether there
is a need to check the validity of a property. For example, it is called to determine the state of each
step in a guided simulation. While you have flexibility in choosing which callback to invoke when
creating the extension, keep in mind the following recommendations:

• The callback <onValidate> is invoked only when the value of the property for which it is defined
is modified. Inside the callback, other properties can be defined or some actions can be invoked in
AIM in response to the property change.

• The callbacks <isValid> and <isVisible> should be considered as "queries" that check only
the validity or visibility of a property. You do not want to use them to change the value of the
property for which they are defined or the value of any other property. You also should not use
them to invoke AIM user interface actions because these callbacks are invoked multiple times. Using
them to perform any change or action could result in subtle errors, often difficult to diagnose.

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
20 of ANSYS, Inc. and its subsidiaries and affiliates.
 Helpful Wizard Creation Information

2.5.2.4. Dynamically Modifying Property Options

As described in Accessing Properties and Their Values (p. 16), a property with the attribute control
set to select or multiselect provides a list of values from which to choose. You define the
choices using the property's attributes. The attribute default specifies the default value.

XML Definition
<property name="ScopingProp" caption="Scoping property" control="scoping" />
<property name="MultiSelectProp" caption="Multi Select Property" control="multiselect" default="Option A,Opt
<attributes readonly-options="Option C" options="Option A,Option B,Option C" />
</property>

In addition to accessing the property value, you can access and possibly modify options that are
available in AIM. To access and modify a list with the possible values for a property, you use
prop.Options.

You can also define options for a property as read-only, which means that they are visible in AIM but
are grayed out, indicating that values cannot be set. The following function definition shows how to
access options for a property. The options are a comma-separated string that you modify to specify
which options are read-only. Read-only options can also be accessed as a comma-separated string
within the IronPython callback.

IronPython Function Definition

def updateStep(step, prop):
properties = step.Properties
multiSelectProp= properties["MultiSelectProp"]
multiSelectPropOptions = multiSelectProp.Options #returns ["Option A", "Option B", "Option C"]
multiSelectPropReadOnlyOptions = multiSelectProp.Attributes["readonly-options"] # returns "Option C"

The options and read-only options defined for the property in the XML file are initial values. You can
use callbacks to dynamically update options, which provides great flexibility for displaying choices
that cannot be statically defined in the XML file.

For example, assume that you want to define a property that allows selection of any of the available
tasks for a given type, such as Geometry.

XML Definition

In the XML file, the options should initially contain an empty string, and no default should be assigned
to the property:
<property name ="GeometryTasks" caption="Task containing geometry" control="select">
<attributes options=""/>

The property options can be filled in by one of the callbacks defined for the step. For example, the
options can be filled in by the callback <refresh> for the step. The callback <refresh> is invoked
when the step is visited to ensure that the list is correctly populated.

IronPython Function Definition

def refreshGeometryOptions(step):
# The geometry tasks are gathered prior to being assigned to the property options
geometryTasks = getGeometryTasks()
prop = step.Properties["GeometryTasks"]
prop.Options.Clear() #make sure that the option list is empty

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 21
AIM Wizards

lastValue = None
for geom in getGeometryTasks():
prop.Options.Add(geom.DisplayText) #add the display text for the task to the option list
lastValue = geom.DisplayText
if prop.ValueString == "" and lastValue != None:
prop.Value = lastValue #if populate the value of the property with the last assigned value
geometryTasks = []
for task in Study.GetAllTasksInProject():
taskIdentifier = task.Container.Name #We use the container since the type is always Task
if taskIdentifier.Contains(modelingTaskIdentifier) or taskIdentifier.Contains(importTaskIdentifier)
geometryTasks.append(task)
return geometryTask

Another situation where dynamic manipulation of options is used involves removing one of the options,
or graying it out so that is visible but not available for selection.

For example, assume that a multi-select property defines options for selecting source terms for different
equations: three momentum sources, plus energy. A separate Boolean variable controls whether to
solve for the energy equation. The source term for energy is not applicable if the energy equation is
not solved.

XML Definition
<property name="SourceTerms" caption="Source terms" control="multiselect" default="">
<attributes readonly-options="" options="Momentum X,Momentum Y,Momentum Z,Energy" />
</property>

<property name="IncludeEnergy" caption="Include Energy Equation" control="boolean" default="False">

<callbacks>
<onvalidate>validateEnergy</onvalidate>
</callbacks>
</property>

The callback <onvalidate> invokes the function validateEnergy, which provides the following
functionality:

• Removes the selection Energy (if present) from the list of values for the property Sources when
the value for the property IncludeEnergy is False.

• Adds Energy to the read-only options so that it cannot be selected.

• Stores the user-selected choice in a global variable so that it can be restored if the energy equation
is re-enabled.

IronPython Function Definition

def validateEnergy(step, prop):
global energySelected
sourceProperty = step.Properties["SourceTerms"]
sourcePropertyValue = sourceProperty.Value
if bool(prop.Value) == False:
if "Energy" in sourcePropertyValue:
sourcePropertyValue.Remove("Energy")
energySelected = True
sourceProperty.Attributes["readonly-options"] = "Energy"
else:
energySelected = False
else:
sourceProperty.Attributes["readonly-options"] = ""

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
22 of ANSYS, Inc. and its subsidiaries and affiliates.
 Helpful Wizard Creation Information

if energySelected:
sourcePropertyValue.Add("Energy")

Note

The function validateEnergy should also be executed when the step is refreshed
to ensure that the values are consistent before visiting the step.

2.5.3. AIM Data Model

The AIM data model is defined via objects that represent the settings that you specify during the
various stages of the workflow (geometry, mesh, physics, and results). The majority of the objects are
associated with tasks in the workflow. Thus, before describing the structure of the data model, it is
useful to review how to access the tasks in your callbacks.

2.5.3.1. Task Representation

In AIM, you create tasks by running a template from the start page or directly in the Workflow view.
Once you have defined your tasks for one or more simulation processes, you can access them via this
query:
Study.GetAllTasksInProject()

A typical list of tasks follows:

['/Geometry Modeling/Task:Task', '/Meshing/Task:Task', '/Physics Definition/Task:Task', '/Solve Physics/Task:Tas

AIM groups the tasks Physics Definition and Solve Physics together into the task group
Physics Solution. However, the association between the data model and the tasks is done using
the tasks that are part of the task group.

To query the list of task groups that are present in the project, you use this query:
Study.GetAllTaskGroupsInProject()

For the example, the list contains a single task group:

['/Study/TaskGroup:TaskGroup 1']

To get the list of the tasks contained in the task group, you use the query GetTasks, which is invoked
using taskGroup:
taskGroup = Study.GetAllTaskGroupsInProject()[0] #gets the first task group
tasksForGroup = taskGroup.GetTasks() #gets the task for the group

For the example, the list contains these tasks:

['/Physics Definition/Task:Task', '/Solve Physics/Task:Task']

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 23
AIM Wizards

To get the task or task group by its visible name, you use its property DisplayText as shown in
the utility functions getTaskByName and getTaskGroupByName, which you can add to your
Python script:
def getTaskByName(displayText):
for task in Study.GetAllTasksInProject():
If task.DisplayText == displayText:
return task
return None

def getTaskGroupByName(displayText):
for taskGroup in Study.GetAllTaskGroupsInProject():
If taskGroup.DisplayText == displayText:
return taskGroup
return None

In addition to the task that AIM displays, scripting uses two other objects to represent AIM tasks: task
component and task object. The following topics explain all three task-related objects:

• Task (p. 24)

• Task Component (p. 24)

• Task Object (p. 25)

2.5.3.1.1. Task
AIM displays objects of type Task. You can use these objects as a starting point to navigate through
other objects. You can also use them to query for other objects that are related to a task, such as
physics regions, structural, flow, or electromagnetic conditions. For more information, see Retrieving
Objects (p. 29).

2.5.3.1.2. Task Component

AIM uses objects of type Component internally to track links and dependencies between tasks. For
example, when you update a task, AIM checks to see if it upstream tasks also need to be updated.

In AIM scripts, you use a task component as an argument to a function that relates to task depend-
encies:

• Update brings a task and its upstream tasks up-to-date.

• Refresh synchronizes a task with the output of other tasks.

• AddSourceToComponentInSystem establishes a connection with other tasks.

Note

As an AIM user, you never need to interact with task component objects. However, if you
access the Project tab, you can see them represented in the Project Schematic. They
are the objects that compose the system named Study.

A task component is the return argument of the command CreateTask. Consider the following
example:

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
24 of ANSYS, Inc. and its subsidiaries and affiliates.
 Helpful Wizard Creation Information

system1 = GetSystem(Name="Study")
meshingComponent = Study.CreateTask(
Type="Meshing",
System=system1,
Input=geometryTaskComponent)

The command CreateTask creates a meshing task. The required arguments are the system (Study)
to which the component belongs and the task component upstream of the meshing component (in
this case a geometry task).

While the return argument of the command CreateTask is a task component, internally a task
and task object are also created.

To invoke the update of the task, you use the object meshingComponent:
meshingComponent.Update()

2.5.3.1.3. Task Object

The task object is responsible for keeping track of the association between the data model and the
tasks. You must provide a taskObject to the command CreateEntity, which creates objects
for the AIM data model.

Consider the following example:

system1 = GetSystem(Name="Study")
study1 = system1.GetContainer(ComponentName="Study")
physicsDefinition = physicsDefinitionComponent.GetTaskObject()
physicsRegion = study1.CreateEntity(
Type="PhysicsRegion",
Association=physicsDefinition)

In this example, physicsDefinitionComponent references the task component for a physics

definition task. You need to access the task object for this component before invoking the command
CreateEntity. The argument Association for the command CreateEntity creates the link
between the task and the created object. Specifically, the object physicsRegion is created and
associated with the task physicsDefinition. For more information about object creation, see
Creating Objects (p. 27).

2.5.3.1.4. Relationships Between Task Objects

As indicated in Task Representation (p. 23), the task object is directly related to the representation
in AIM, which is why it is often the starting point for a function invoked from a callback. If you have
a geometry task named valve, you can use the function getTaskByName to access it:
task = getTaskByName("valve")

To access the task component for this task, you use the query GetComponentReference:
taskComponent = task.GetComponentReference()

To access the task object from either the task or task component, you use the function GetTaskOb-
ject:
taskObject = task.GetTaskObject()

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 25
AIM Wizards

taskObject = taskComponent.GetTaskObject()

2.5.3.1.5. Task Usage Example

The following code samples are for a step in an AIM wizard. They assume that one or more geometry
tasks are defined in the project. The update function of the step adds a mesh task, a physics task
group, and a results task. To see more complex examples of workflow creation, you can look at the
journals that are recorded when you run templates from the AIM start page.

XML Definition
<step name="CreateWorkflowFromGeometry" caption="Create Workflow From Geometry: Model" version="1">
<property name ="GeometryTasks" caption="Task containing geometry" control="select">
<attributes options=""/>
</property>
<callbacks>
<onrefresh>refreshGeometryOptions</onrefresh>
<onupdate>createStructuralSimulationProcess</onupdate>
</callbacks>
</step>

IronPython Function Definition

def refreshGeometryOptions(step):
prop = step.Properties["GeometryTasks"]
prop.Options.Clear()
lastValue = None
for geom in getGeometryTasks():
prop.Options.Add(geom.DisplayText)
lastValue = geom.DisplayText
if prop.ValueString == "" and lastValue != None:
prop.Value = lastValue

def getGeometryTasks():
modelingTaskIdentifier = "Geometry Modeling"
importTaskIdentifier = "Import"
geometryTasks = []
for task in Study.GetAllTasksInProject():
taskIdentifier = task.Container.Name #We use the container since the type is always Task
if taskIdentifier.Contains(modelingTaskIdentifier) or taskIdentifier.Contains(importTaskIdentifier):
geometryTasks.append(task)
return geometryTasks

def createStructuralSimulationProcess(step):
#Retrieves the user input
geometryTaskName = step.Properties["GeometryTasks"].Value
#Retrieves the Task from its name
geometryTask = getTaskByName(geometryTaskName)
#Retrieves the component reference from the task
geometryComponent = geometryTask.GetComponentReference()

system1 = GetSystem(Name="Study")
#Creates mesh task
meshingComponent = Study.CreateTask(
Type="Meshing",
System=system1,
Input=geometryComponent)
meshingTaskObject = meshingComponent.GetTaskObject()
meshingTaskObject.EngineeringIntent = "StructuralOrThermalOrElectricConduction"
meshingComponent.Refresh()

# Create physics definition task

physicsDefinitionComponent = Study.CreateTask(
Type="Physics Definition",
System=system1,
Input=meshingComponent)
physicsDefinitionComponent.Refresh()

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
26 of ANSYS, Inc. and its subsidiaries and affiliates.
 Helpful Wizard Creation Information

physicsDefinition = physicsDefinitionComponent.GetTaskObject()
physicsDefinition.CalculationType = "Static"

# Create physics solve task

solvePhysicsComponent = Study.CreateTask(
Type="Solve Physics",
System=system1,
Input=solveUpstreamComponent)
solvePhysicsComponent.Refresh()

# Create physics group

physicsSolutionGroup = Study.CreateGroup(Name="Physics Solution")
physicsSolutionGroup.Add(Component=physicsDefinitionComponent)
physicsSolutionGroup.Add(Component=solvePhysicsComponent)

#Adds results task

resultsEvaluationComponent = Study.CreateTask(
Type="Results Evaluation",
System=system1,
Input=solvePhysicsComponent)
#Establishes connection between the physics definition and the results task
AddSourceToComponentInSystem(
SourceComponent=physicsDefinitionComponent,
TargetComponent=resultsEvaluationComponent)
resultsEvaluationComponent.Refresh()

2.5.3.2. Data Model Objects

When using AIM, you create objects as you work through the tasks in your workflow. In a custom
extension, you also typically need to create objects and set their properties. You also need to retrieve
objects and their properties to make changes to existing objects.
2.5.3.2.1. Creating Objects
2.5.3.2.2. Retrieving Objects
2.5.3.2.3. Saving and Restoring Data for Guided Simulations

2.5.3.2.1. Creating Objects

You create objects using the command CreateEntity. For all objects, this command requires the
following arguments:

• Type. The type of object to create.

• Association. The parent object for the object being created.

Other optional arguments depend on the specific object being created. They are used to set the
properties of the object.

For a specific object, the easiest way to obtain the information for the command CreateEntity
is to create the object in AIM and then look at what is recorded in the AIM journal.

While most of the information is object-specific, there are some general guidelines of which you
should be aware:

• In AIM, you can obtain the type of a given object by visiting the page where the object properties
are displayed and hovering the mouse cursor next to the image for the object.

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 27
AIM Wizards

• For the majority of objects, the parent to use for the association is the task object corresponding to
the task for which the object is created:
physicsRegion = study1.CreateEntity(
Type="PhysicsRegion",
Association=physicsDefinition)
physicsRegion.PhysicsType = "Structural"
materialAssignment1 = study1.CreateEntity(
Type="MaterialAssignment",
Association=physicsDefinition)

• For objects created from a task for fluid flow simulation, objects associated with the task object in-
clude physics region, solver settings, and material assignment. The majority of the other objects,
such as fluid condition, interface conditions, and numerical controls, are specific to a given physics
region. Thus, they are associated with the appropriate physics region:
physicsRegion1 = study1.CreateEntity(
Type="PhysicsRegion",
Association=physicsDefinition)
physicsRegion1.PhysicsType = "Fluid"
materialAssignment2 = study1.CreateEntity(
Type="MaterialAssignment",
Association=physicsDefinition)
inletCondition1 = study1.CreateEntity(
Type="InletBoundary",
Association=physicsRegion1)

• Deleting the parent object results in the deletion of all the objects associated with it. For example,
deleting a physics region in a flow task also deletes all fluid flow conditions associated with this region.

You can gather the arguments that set the properties of the object by looking at the object properties
in the Discovery AIM and Workbench Scripting Guide. Because the arguments are optional, they don’t
need to be specified during object creation. They can be set from the object returned from the
command CreateEntity:
inletCondition2 = study1.CreateEntity(
Type="InletBoundary",
Association=physicsRegion1) #creates an inlet object

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
28 of ANSYS, Inc. and its subsidiaries and affiliates.
 Helpful Wizard Creation Information

#set the properties for the inlet

inletCondition2.Flow.Option = "Pressure"
inletCondition2.Flow.Pressure.GaugeTotalPressure = "100 [Pa]"
inletCondition2.Location = ["FACE18"]

While properties are specific to a given object, the following information is common to all objects:

• Name. A unique name that AIM assigns to the object for internal use. You cannot change the name.
You can see the name and object type in AIM by hovering the mouse cursor next to the image for
the object.

• DisplayText. The user-defined and editable name that AIM is to display for the object.

• Type. The type of object. To gather this information, you should use the query
Study.GetEntityType(Entity=object). You should not use object.Type because it
returns an internal type that can be different from the one that AIM displays.

2.5.3.2.2. Retrieving Objects

To retrieve objects that already exist in your project, you use the object properties Name, Display-
Text, and Type. To obtain all objects of a given type, you use this query, where type is the object
type:
Study.GetAllObjectsOfType(Type = type)

For example, the following query returns all objects of the type Support:
Study.GetAllObjectOfType(Type = "Support")

If you have multiple simulation processes in your projects, you might need to access only the objects
associated with one of the tasks in your simulation process. In this case, you can invoke the query
GetAllObjectsOfType from the task of interest to get these objects.

Assume that you have two Physics Solution task groups with assigned display texts of
Physics 1 and Physics 2 and you want to get the support objects for only the first task group.
Because the support objects are associated with the physics definition task of your task group, you
first need to access the task from the task group list:
taskGroup = getTaskGroupByName("Physics 1")
task = taskGroup.GetTasks()[0] #physics definition task is the first task of the group
supports = task.GetObjectsOfType(Type="Support") #gets the support for a given type

Note

Although internally the support objects are associated with the taskObject, you can
directly use the task or task group that you see in AIM to query the information.

Another common scenario related to object query is the need to query one specific object. You can
use the query GetObjectOfTypeAndName for this purpose. The arguments of the query are Type
and Name for the object that you want to query. If you want to query using DisplayText rather
than the internal name, you should add "@" to the string that represents the DisplayText.

The following query retrieves an object of type Support with DisplayText set to BeamSupport:

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 29
AIM Wizards

Study.GetObjectsOfTypeAndName(Type = "Support", Name="@BeamSupport")

Because the display text does not have to be unique, if multiple objects with the same display text
exist, the query returns the first one that is found. If you want to query the object by its unique
name, you should not add "@" to the string representing the name:
Study.GetObjectsOfTypeAndName(Type = "Support", Name="Support 2")

Again, to see the unique internal name, you hover the mouse cursor over the object in AIM.

To simplify the syntax of the query that searches an object by type, you can also use auto-generated
queries that explicitly contain the type of the object for which you are querying:
system1 = GetSystem(Name="Study")
study1 = system1.GetContainer(ComponentName="Study")
study1.GetSupport(Name="@BeamSupport")

These two queries are equivalent:

Study.GetObjectsOfTypeAndName(Type = "Support")

study1.GetSupport(Name="@BeamSupport")

However, the automatically generated query should be explicitly invoked on the variable study1
as demonstrated earlier.

The same logic applies to all types. For the type SelectionSet, the following two queries obtain
an object selectionSet named supportFaces:
Study.GetObjectsOfTypeAndName(Type = "SelectionSet", Name="@supportFaces")

study1.GetSelectionSet(Name="@supportFaces")

2.5.3.2.3. Saving and Restoring Data for Guided Simulations

As described in Guided Simulations (p. 5), a guided simulation is an extension for which the attribute
persistent = true is specified in the wizard definition. When you close a guided simulation,
its data is persisted, which means that AIM automatically populates your last choices when you reopen
the guided simulation. Because your choices are saved with the project, AIM also automatically
populates them when you open a guided simulation after saving and resuming a project.

Because you can make changes after a guided simulation is closed, you need to pay special attention
to how you create and access objects in your callbacks. Specifically, you need to ensure that:

• Your callbacks create objects in the AIM data model the first time that they are executed, but that
they do not duplicate object creation when you modify your inputs.

• You store the information about the objects that you created so you can retrieve them and modify
their properties.

The easiest way to separate object creation from object modification is to define a callback <oncre-
ate> in addition to a callback <onupdate> as described in Defining Step Callbacks (p. 9). Because
the callback <oncreate> is invoked only once, you use it to create the AIM objects for the step’s

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
30 of ANSYS, Inc. and its subsidiaries and affiliates.
 Helpful Wizard Creation Information

properties. After the first update, when you need to update existing object properties but not create
new properties, you use the callback <onupdate>.

Using step.Attributes is a convenient way to store and retrieve an object. In it, you can store
the name of the object and use the methods described in Retrieving Objects (p. 29) to access the
created object:
#In the oncreate callback, create a physics region and store the name of the object
physicsRegion = study1.CreateEntity(
Type="PhysicsRegion",
Association=physicsDefinition)
physicsRegion.PhysicsType = "Structural"
physicsRegion.Location=["BODY1"]
step.Attributes["fluidPhysicsRegionName"] = fluidPhysicsRegion.Name

#in the onupdate callback, retrieve the physics region and modify its properties
physicsRegionName = step.Attributes["fluidPhysicsRegionName"]
system1 = GetSystem(Name="Study")
study1 = system1.GetContainer(ComponentName="Study")
physicsRegion = Study.GetPhysicsRegion(Name=physicsRegionName)
physicsRegion.Location=["BODY2"]

For the case where you need to save a taskComponent, you can include in your IronPython script
the utility function getComponentByName to retrieve it:
#In the oncreate callback, create a meshing task. meshingComponent is the return argument
meshingComponent = Study.CreateTask(
Type="Meshing",
System=system1,
Input=geometryComponent)
step.Attributes["meshingComponentName"] = meshingComponent .Name

#in the onupdate callback, retrieve the meshingComponent

meshingComponentName = step.Attributes["meshingComponentName"]
meshingComponent = getCompomentByName(meshingComponentName)

def getCompomentByName(componentName):
#componentName = component.Name
for component in GetSystem(Name="Study").Components:
if component .Name == componentName:
return component
return None

2.5.4. AIM Interface Interaction

The majority of actions executed in callbacks are related to either setting AIM data from ACT-based
properties or querying AIM data or ACT-based properties for the purpose of controlling the appearance
of AIM. In some cases, you might want to control the behavior of the AIM user interface from within
a script, both for properties or step-related callbacks. The Discovery AIM and Workbench Scripting Guide
describes the interface actions that the namespace StudyUI provides for this purpose.

While interface actions are equivalent to commands from a syntax standpoint, they are executed behind
the scenes in a different way. Commands provide the ability to directly manipulate data. Interface actions
are requests to the AIM interface to perform certain actions. The AIM interface processes and queues
the requests and then executes them at the proper time.

Interface actions are available for:

2.5.4.1. Making a Given Object Visible in the Graphics Window
2.5.4.2. Saving the Image in the Graphics Window to a File

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 31
AIM Wizards

2.5.4.3. Setting the Selection Filter to a Specific Topological Entity

2.5.4.4. Controlling the Visibility for Topological Entities
2.5.4.5. Associating Geometry Information with Your Extension

2.5.4.1. Making a Given Object Visible in the Graphics Window

AIM controls what object displays in the graphics window. When writing a custom extension, you
can decide what object AIM is to display. You can achieve this by invoking the action StudyUI.SetSe-
lectionTo(Entity = objectReference), where objectReference is the object to display.
The object is usually available as a return argument of the command that is used to create the object.
Some examples follow.

2.5.4.1.1. Displaying the Imported Geometry

In a multi-step custom extension, typically the first step imports a geometry. Being able to display
the geometry is a crucial requirement because it provides scoping properties in subsequent steps.
The following code sample creates an import task, defines the path of the file to import, and updates
the task. Once the task is updated, the interface action SetSelectionTo displays the imported
geometry in the graphics window.
system1 = GetSystem(Name="Study")
importComponent = Study.CreateTask(
Type="Import",
System=system1)
importTaskObject = importComponent .GetTaskObject()
importTaskObject.ChooseImportSources(FilePaths=pathOfFileToBeImported)
importComponent.Update()
StudyUI.SetSelectionTo(Entity = importTaskObject)

2.5.4.1.2. Displaying a Physics-related Object

For a physics-related object in AIM, such as a structural, fluid, or electro-magnetic condition, the
graphics window displays a symbol representing the condition that is applied. You can achieve the
same result in your custom extension by invoking the interface action SetSelectionTo, passing
the object that you’ve created as the argument. The following code sample creates, defines, and
displays a pressure object in the graphics window.
system1 = GetSystem(Name="Study")
study1 = system1.GetContainer(ComponentName="Study")
physicsDefinitionComponent1 = system1.GetComponent(Name="Physics Definition")
physicsDefinition1 = physicsDefinitionComponent1.GetTaskObject()
pressure1 = study1.CreateEntity(
Type="Pressure",
Association=physicsDefinition1)
pressure1.Location = ["FACE15"]
pressure1.Magnitude = "111 [Pa]"
StudyUI.SetSelectionTo(Entity = pressure1)

2.5.4.1.3. Displaying a Computed Result

In the following XML code, Step3 updates a results task and creates three postprocessing objects:
displacement magnitude, equivalent stress, and full stress. Next, Step4 displays a property that allows
the user to choose one of the computed results and display it in the graphics window.

XML Definition

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
32 of ANSYS, Inc. and its subsidiaries and affiliates.
 Helpful Wizard Creation Information

<!-- Sample step to update a results task-->

<step name="Step3" caption="Update Results" version="1" context="Study">
<description></description>
<callbacks>
<onupdate>updateResultsStep</onupdate>
</callbacks>
</step>
<step name="Step4" caption="Results Display" version="1" context="Study">
<description>Display and summary of computed results.</description>
<property name="resultToDisplay" caption="Display result" control="select">
<attributes presentation="radio" options="Displacement magnitude, Equivalent stress, Full stress" />
<callbacks>
<onvalidate>evaluateResults</onvalidate>
</callbacks>
</property>
</step>

IronPython Function Definition

def updateResultsStep(step, prop):

#Assumes that you created the geometry mesh and physics task
global solvePhysicsComponent1, physicsDefinitionComponent1, resultsEvaluationComponent1
# References to created objects are stored for re-use in the evaluate callback
global displacementMagnitude, equivalentStress, fullStress

resultsEvaluationComponent1 = Study.CreateTask(
Type="Results Evaluation",
System=system1,
Input=solvePhysicsComponent1)
AddSourceToComponentInSystem(
SourceComponent=physicsDefinitionComponent1,
TargetComponent=resultsEvaluationComponent1)
resultsEvaluationComponent1.Refresh()
results1 = resultsEvaluationComponent1.GetTaskObject()
displacementMagnitude = study1.CreateEntity(
Type="ContourResult",
Association=results1)
displacementMagnitude.Variable = "Displacement.mag"
displacementMagnitude.DisplayText = "Displacement magnitude"
equivalentStress = study1.CreateEntity(
Type="ContourResult",
Association=results1)
equivalentStress.Variable = "Stress.eqv"
equivalentStress.DisplayText = "Equivalent stress"
plane1 = study1.CreateEntity(
Type="Plane",
Association=results1)
plane1.Definition.Origin.DefineBy = "Location"
plane1.Definition.Axis1.Direction.DefineBy = "Location"
fullStress = study1.CreateEntity(
Type="ContourResult",
Association=results1)
fullStress.Variable = "Stress.p1"

resultsEvaluationComponent1.Update()

def evaluateResults(step, prop):

# References to objects created in the update callback
global displacementMagnitude, equivalentStress, fullStress
resultSelect = step.Properties["resultToDisplay"].Value

if resultSelect == "Displacement magnitude"):

StudyUI.SetSelectionTo(Entity = displacementMagnitude)
elif resultSelect == "Equivalent stress"):
StudyUI.SetSelectionTo(Entity = equivalentStress)
elif resultSelect == "Full stress":
StudyUI.SetSelectionTo(Entity = fullStress)

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 33
AIM Wizards

2.5.4.2. Saving the Image in the Graphics Window to a File

AIM provides the ability to save the image in the graphics window to a file. During the execution of
a custom extension, the execution of a callback can update the graphics window, as described in the
previous section. If you want to save the image to a file during the execution of the callback, you can
add the interface action SaveImage to your script. Images are saved in PNG format. You can choose
between different resolutions, ranging from 640x480 to 3840x2160 pixels.
displacementMagnitude = study1.CreateEntity(
Type="ContourResult",
Association=results1)
displacementMagnitude.Variable = "Displacement.mag"
displacementMagnitude.DisplayText = "Displacement magnitude"
StudyUI.SetSelectionTo(Entity = displacementMagnitude)
StudyUI.SaveImage(FilePath=fullPathOfTheFile, Size="1920x1080")

2.5.4.3. Setting the Selection Filter to a Specific Topological Entity

Custom extensions often contain properties with controltype="scoping", which require users
to make selections. Typically a correct selection involves a specific topological entity, such as a body
for selections related to physics regions and material assignments or a face for selections related to
most structural, flow, and electromagnetic conditions (support, inlet, wall, and other conditions). To
improve the user experience, you can set the selection filter to the topology type that is appropriate
for the selection presented in a step. This is achieved by invoking the interface action SetSelec-
tionFilter:
StudyUI.SetSelectionFilter(Filter=topologyType)

Where topologyType is a string that can be set to Body, Face, or Edge.

You should include the invocation of StudyUI.SetSelectionFilter on the refresh callback of

a given step so that it takes place when the properties display.

2.5.4.4. Controlling the Visibility for Topological Entities

When dealing with a complex geometry in AIM, you might interactively hide one or more topological
entities (bodies or faces). You can achieve this same result in your script by invoking the interface
actions HideBodies and HideFaces. To restore full visibility once you no longer want to hide the
bodies or faces, you invoke the method ShowAll.
StudyUI.HideBodies(Bodies = [listOfBodies] #hides one or more specified bodies
StudyUI.HideFaces(Faces = [listOfFaces] #hides one or more specified faces
StudyUI.ShowAll() #Restores full visibility

The following code sample shows you how to hide a specific physics region. For this region, the
property Location contains a list of bodies, which is passed as the argument of HideBodies:
study1 = system1.GetContainer(ComponentName="Study")
physicsRegion = study1.GetPhysicsRegion(Name="PhysicsRegion 1")
StudyUI.HideBodies(Bodies=physicsRegion.Location)

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
34 of ANSYS, Inc. and its subsidiaries and affiliates.
 Helpful Wizard Creation Information

2.5.4.5. Associating Geometry Information with Your Extension

During an AIM session, you can work with multiple simulation processes, which can include different
geometry files. AIM uses the information from the Workflow view to understand how the tasks and
their objects are associated with a given geometry model. When working with a custom extension,
it is not possible to determine what steps are associated with a geometry. Therefore, you must provide
this information by invoking the command SetCurrentModelForExtension.

The easiest way to provide the model information is in the callback that executes a geometry import.
As described in Controlling the Visibility for Topological Entities (p. 34), after importing a geometry,
you must make it visible in the graphics window. You add the command SetCurrentModelForEx-
tension to make AIM aware that your extension will work with this geometry model:
system1 = GetSystem(Name="Study")
importComponent = Study.CreateTask(
Type="Import",
System=system1)
importTaskObject = importComponent .GetTaskObject()
importTaskObject.ChooseImportSources(FilePaths=pathOfFileToBeImported)
importComponent.Update()
StudyUI.SetSelectionTo(Entity = importTaskObject)
model = Study.GetModelFromObject(Object=importTaskObject)
Study.SetCurrentModelForExtension(Model = model)

The next-to-last line shows how to gather the model information, based on your import task:
model = Study.GetModelFromObject(Object=importTaskObject)

The final line shows how to set the model:

Study.SetCurrentModelForExtension(Model = model)

Once the model is set, your custom template or guided simulation remains aware of it until the end
of its execution. For a guided simulation, you must invoke the command again when the execution
is resumed.

If you don’t associate the geometry model with your extension, some functionality in your application
will not work:

• An interface action for hiding and showing the topological entity will throw an error when the action
is invoked.

• Editing the location in AIM will not highlight the location in the graphics window.

You also need the model association if you are performing an action or query that involves geometry
information. If you use SetCurrentModelForExtension to set your model, you can use Get-
CurrentModelForExtension to retrieve this information.

The following code sample validates that the selection of a given scoping property is a body. You
can use the query GetGeometryReferenceTypes to validate the topology type. Arguments to
the query are the location set that you want to validate and the model that defines the geometry.

XML Definition
<property name="Bodies" caption="Bodies forming region" control="scoping" >
<callbacks>
<isValid>isBodySelectionValid</isValid>

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 35
AIM Wizards

</callbacks>
</property>

IronPython Function Definition

def isBodySelectionValid(step, prop):

if step.Properties["Bodies"].Value == None:
return False
locationSet = step.Properties["Bodies"].Value.LocationSet
geometryDefinitionObject = meshingUpstreamTask.GetTaskObject()
model = Study.GetCurrentModelForExtension()
selectionTypes = Study.GetGeometryReferenceTypes(LocationSet = locationSet, Model = model)
if len(selectionTypes) > 1 or len(str(selectionTypes[0]).find("Body")) < 0:
prop.StateMessage = "Invalid selection"
return False

2.5.5. Miscellaneous Wizard-Related Information

The following topics supply supplemental information about wizards:
2.5.5.1. Providing Custom Wizard Help
2.5.5.2. Setting Script Versions

2.5.5.1. Providing Custom Wizard Help

In AIM, you can access two types of help:

• Step-level help, which displays by default in AIM's context-sensitive help panel. If you hide this panel,
you can click the question mark icon in the step's header to display it again.

• Property-level help, which displays when you click the help button to the right of a property within
a step.

You can define both types of help for your custom wizards.

Step-Level Help
To provide custom help for wizard steps, you create HTML files that you then store in a child folder
in the extension's folder. The element <step> in the extension's XML file references the help file for
the step via the attribute helpFile. You use this attribute to reference the relative path for the
HTML file to display in the step's help panel.

In the example below, help for the step named Step1 is provided in an HTML file located in the
subfolder help for the extension:
<step name="Step1" caption="Load geometry file" version="1" context="Study" helpFile="help/StudyDemo1.html">

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
36 of ANSYS, Inc. and its subsidiaries and affiliates.
 Custom Template Examples

If you give the help files for steps the same names as the steps themselves and then store these files
in a folder named help, you do not need to use the attribute helpFile to reference them. The
extension automatically finds and displays the appropriate help for each step. If, however, you give
the folder in which the help files are stored some other name, you must use the attribute helpFile
to reference the relative path.

Property-Level Help
To provide custom help for the properties that are defined within a step, you can either create HTML
files or define help text directly in the extension's XML file.

If you choose to create HTML files for properties, you can use the attribute helpfile in the element
<property> to point to the help file for this property.

If you give the help file the same name as the step and the property, separated by an underscore,
you do not need to use the attribute helpFile to explicitly reference the file. For example, assume
that MeshingStep is the step name and MeshResolution.html is the property name. The help
file for the property must be named MeshingStep_MeshResolution.html.

If you prefer to define the content for property-level help in the extension's XML file you use the
element <help> to define the text to display. Examples follow for properties named Geometry and
nAnalysis.
<property name="Geometry" caption="Geometry filename" control="fileopen" default="ANSYSInputs"> <help>The geomet

<property name="nAnalysis" caption="Number of analyses" control="fileopen" default=""> <help>The number of stati

Note

When using HTML files for properties, the recommended practice is to avoid images and
to limit the text to no more than 200 characters.

2.5.5.2. Setting Script Versions

When creating a callback for an AIM extension, to ensure that any migration can occur in a subsequent
release, the best practice is to insert the following code for setting and resetting script versions for
each function in the IronPython script. This ensures that the commands being used today are correctly
executed and that the product version is kept at the version where the extension is used.
# Store current Script Version
currentVersion = GetScriptVersion()
# Set the Script Version to the appropriate version
SetScriptVersion(Your version)
# Insert your script
...
# Reset the Script Version
SetScriptVersion(currentVersion)

2.6. Custom Template Examples

Two supplied extensions provide examples of AIM custom templates for target product wizards:
2.6.1. Custom Template (Single-Step)
2.6.2. Custom Template (Multiple-Step)

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 37
AIM Wizards

2.6.1. Custom Template (Single-Step)

The supplied extension StudyDemo contains a target product wizard for AIM that implements a single-
step custom template:
2.6.1.1. Creating the Single-Step Custom Template
2.6.1.2. Defining Functions for the Single-Step Custom Template

2.6.1.1. Creating the Single-Step Custom Template

The target product wizard StudyDemo1 imports a Geometry file. The XML file follows. In the element
<wizard>, the attribute name is set to StudyDemo1. The attribute context is set to Study.
<extension version="1" name="StudyDemo">
<author>ANSYS Inc.</author>

<guid shortid="StudyDemo">150c0680-292b-4291-b46d-bac59949cd56</guid>

<script src="main.py" />

<interface context="Study">
<images>images</images>
</interface>

<wizard name="StudyDemo1" version="1" context="Study" icon="icon">

<description>Wizard to demonstrate the concept inside AIM.</description>

<step name="Step1" caption="Load geometry file" version="1" context="Study" helpFile="help/StudyDemo1.html">

<description>Import a geometry file.</description>

<callbacks>
<onupdate>action</onupdate>
<onreset>reset</onreset>
</callbacks>

<property name="Geometry" caption="Geometry filename" control="fileopen" default="ANSYSInputs">

<help>The geometry file to import.</help>
<property name="NAnalysis" caption="Number of analyses" control="integer" default="1">
<help>The number of static structural analyses to create. You must enter an integer greater than 0.</help>
<callbacks>
<isvalid>isvalid</isvalid>
</callbacks>
</property>

</step>

</wizard>

</extension>

Step Definition
The wizard StudyDemo1 has only a single step named Step1. The optional attribute helpFile
sets the custom help file to display for this step.

Note

The attribute context is not used in step definitions for a target product wizard for AIM.

Callback Definition
A summary follows of the callbacks defined for this single step:

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
38 of ANSYS, Inc. and its subsidiaries and affiliates.
 Custom Template Examples

• The callback <onupdate> executes the function action, which creates the AIM study.

• The callback <onreset> executes the function reset, which allows you to reset (delete) the data
created in other callbacks.

Property Definition
A summary follows of the properties defined for this single step:

• For the property Geometry, the attribute control is set to fileopen, which displays a file selection
property initialized to the default attribute value. The child element <help> indicates the text
message to display as the custom help for this property: The geometry file to import.

• For the property NAnalysis, the attribute control is set to integer, which allows the integer
value for the default attribute to be edited. The child element <help> indicates the text message
to display as the custom help for this property: The number of static structural ana-
lyses to create. You must enter an integer greater than 0.. The callback
<isvalid> invokes the function isvalid, which validates that the entered integer is not less than
1. A custom message can be displayed when the entered value fails validation.

2.6.1.2. Defining Functions for the Single-Step Custom Template

Callbacks for wizard steps are defined in the IronPython script referenced by the extension’s XML file.
The extension StudyDemo references the following script main.py.
tasksToDelete = []
groupsToDelete = []

def action(step):
global tasksToDelete,groupsToDelete
tasksToDelete = []
groupsToDelete = []
system1 = GetSystem(Name="Study")
importComponent1 = Study.CreateTask(
Type="Import",
System=system1)
tasksToDelete.Add(importComponent1)
study1 = system1.GetContainer(ComponentName="Study")
import1 = importComponent1.GetTaskObject()
geometryImportSource1 = study1.CreateEntity(
Type="GeometryImportSource",
Association=import1)
geometryImportSource1.FilePath = step.Properties["Geometry"].Value
geometryImportSource1.GenerateImportSourceOperation()

step.UpdateProgressInformation(10.)

pct = 10.
for i in range(step.Properties["NAnalysis"].Value):
meshingComponent1 = Study.CreateTask(
Type="Meshing",
System=system1,
Input=importComponent1)
tasksToDelete.Add(meshingComponent1)
meshingComponent1.Refresh()
physicsSolutionGroup1 = Study.CreateGroup(Name="Physics Solution")
groupsToDelete.Add(physicsSolutionGroup1)
physicsDefinitionComponent1 = Study.CreateTask(
Type="Physics Definition",
System=system1)
tasksToDelete.Add(physicsDefinitionComponent1)
solvePhysicsComponent1 = Study.CreateTask(
Type="Solve Physics",
System=system1)

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 39
AIM Wizards

tasksToDelete.Add(solvePhysicsComponent1)
physicsSolutionGroup1.Add(Component=physicsDefinitionComponent1)
physicsSolutionGroup1.Add(Component=solvePhysicsComponent1)
AddSourceToComponentInSystem(
SourceComponent=physicsDefinitionComponent1,
TargetComponent=solvePhysicsComponent1)
AddSourceToComponentInSystem(
SourceComponent=meshingComponent1,
TargetComponent=physicsDefinitionComponent1)
physicsDefinitionComponent1.Refresh()
solvePhysicsComponent1.Refresh()
physicsDefinition1 = physicsDefinitionComponent1.GetTaskObject()
physicsRegion1 = study1.CreateEntity(
Type="PhysicsRegion",
Association=physicsDefinition1)
solverSettings1 = study1.CreateEntity(
Type="SolverSettings",
Association=physicsDefinition1)
transcript1 = study1.CreateEntity(
Type="Transcript",
Association=physicsDefinition1)
physicsDefinitionComponent1.Refresh()
solvePhysicsComponent1.Refresh()
meshing1 = meshingComponent1.GetTaskObject()
meshing1.EngineeringIntent = "StructuralOrThermalOrElectricConduction"
physicsRegion1.Location = ["BODY1"]
physicsRegion1.PhysicsType = "Structural"
materialAssignment1 = study1.CreateEntity(
Type="MaterialAssignment",
Association=physicsDefinition1)
materialAssignment1.Location = ["BODY1"]
material1 = study1.CreateEntity(
Type="Material",
Association=physicsDefinition1)
material1.ImportEngineeringData(Name="Structural Steel")
materialAssignment1.Material = material1
pct += 10.
step.UpdateProgressInformation(pct)

if i==9:
raise UserErrorMessageException("My own error message.")

def reset(step):
global tasksToDelete,groupsToDelete
system1 = GetSystem(Name="Study")
for group in groupsToDelete:
Study.DeleteTaskGroup(Group=group)
for task in tasksToDelete:
task.DeleteTask(System=system1)

def isvalid(step, prop):

if prop.Value<1:
prop.StateMessage = "Must be greater than 0."
return False
return True

Descriptions follow of the functions defined in this script:

• The function action is the single step in the custom template. When Create Simulation is clicked,
the callback <onupdate> is invoked. It creates the Study workflow by creating and updating the
Geometry, Mesh, and Physics tasks.

• The callback <onreset> invokes the function reset, which allows you to reset (delete) the data
created in other callbacks.

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
40 of ANSYS, Inc. and its subsidiaries and affiliates.
 Custom Template Examples

• The callback <isvalid> in the element <property> invokes the function isvalid, which validates
that the property value entered is not less than 1. A custom message can be displayed when the
entered value fails validation.

2.6.2. Custom Template (Multiple-Step)

The supplied extension PressureLossMultiple contains a target product wizard for AIM that
implements a muliple-step custom template:
2.6.2.1. Creating the Multiple-Step Custom Template
2.6.2.2. Defining Functions for the Multiple-Step Custom Template

2.6.2.1. Creating the Multiple-Step Custom Template

The wizard PressureLossMultiple imports a Geometry file, refines the mesh, defines the load,
and exports the maximum velocity. The XML file follows. In the element <wizard>, the attribute
name is set to PressureLossMultiple. The attribute context is set to Study.
<extension version="1" name="PressureLossMultiple" icon="images\loss.png">
<guid shortid="AimMultiStepWizard">C3F86496-2F13-49E3-B7D0-353542207EAE</guid>
<author>ANSYS Inc.</author>
<description>Demonstration of a pressure loss in AIM.</description>

<script src="pressureLoss.py" />

<interface context="Project">
<images>images</images>
</interface>

<wizard name="PressureLossMultiple" version="1" context="Study" icon="loss">

<description>This wizard is for demonstration of ACT wizard capability in AIM.</description>

<step name="Step1" caption="Import the geometry" version="1" context="Study" HelpFile="help/Step1.html">

<description>Import the geometry file and create the workflow.</description>

<callbacks>
<onupdate>importGeometry</onupdate>
</callbacks>

<property name="geometryfile" caption="geometry file" control="fileopen" default="E:\Geometry\TubeSelectio

</step>

<step name="Step2" caption="Refine the mesh" version="1" HelpFile="help/Step2.html">

<description>Refine the mesh from Low to High.</description>

<callbacks>
<onupdate>refineMesh</onupdate>
</callbacks>

<property name="MeshResolution" caption="mesh resolution" control="integer" default="1"/>

</step>

<step name="Step3" caption="Define the loads" version="1" HelpFile="help/Step3.html">

<description>Specify the loads to applied on the geometry.</description>

<callbacks>
<onupdate>setup</onupdate>
</callbacks>

<property name="Velocity" caption="Velocity" control="float" unit="Velocity" default="0.1 [m s^-1]"/>

<property name="InletLocation" caption="InletLocation" control="scoping" />

<property name="GaugePressure" caption="Gauge Pressure" control="float" unit="Pressure" default="0 [Pa]

<property name="OutletLocation" caption="OutletLocation" control="scoping" >
<callbacks>

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 41
AIM Wizards

<isvalid >isValid</isvalid>
</callbacks>
</property>
</step>

<step name="Step4" caption="Export the maximum velocity" version="1" HelpFile="help/Step4.html">

<description>Here we are just exposing the value of the maximum velocity and the pressure loss.</descript

<property name="MaximumVelocity" caption="Maximum Velocity" control="float" unit="Velocity" readonly = "T

<property name="PressureLoss" caption="Pressure Loss" control="float" unit="Pressure" readonly = "True"/>
</step>
</wizard>

</extension>

Step Definition

The wizard PressureLossMultiple has four steps. The optional attribute helpFile sets the
custom help file to display for the step.

A summary follows of the steps for this wizard:

• Step1: Imports the geometry and creates the workflow in AIM.

– The property geometryfile enables you to specify a geometry. You can either keep the geometry
specified by the attribute default or browse to select a different one (control="fileopen").
For this example, a geometry file named TubeSelectionSet.agdb is selected.

– The callback <onupdate> is invoked when Next is clicked. It executes the function importGeo-
metry, which imports the selected geometry and then creates the workflow in AIM. Specifically,
it creates the workflow from journal content included in the function.

– The attribute HelpFile is set to Step1.html.

• Step2: Refines the mesh for the geometry from low to high.

– The property MeshResolution enables you to set the resolution for the mesh. This property
has a default of 1 (default="1") and accepts only integer values (control="integer").

– The callback <onupdate> is invoked when Next is clicked. It executes the function refineMesh,
which creates a mesh according to the specification.

– The attribute HelpFile is set to step2.html.

• Step3: Defines the loads applied on the geometry.

– The properties Velocity and GaugePressure enable values to be entered (con-

trol="float").

– The properties InletLocation and OutletLocation require the inlet and outlet locations
to which to apply the load (control="scoping") to be defined.

– When a value is entered for the outlet location, the callback <isvalid> is invoked. It executes
the function isValid, which verifies that the inlet and outlet locations are not the same.

– The callback <onupdate> invokes the function setup when Next is clicked. This function applies
the loads to the selected locations and performs the calculations.

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
42 of ANSYS, Inc. and its subsidiaries and affiliates.
 Custom Template Examples

– The attribute HelpFile is set to step3.html.

• Step4: Exposes the maximum velocity and pressure loss results.

– The properties MaximumVelocity and PressureLoss show the calculated values in read-only
format (readonly="true").

– The attribute HelpFile is set to step4.html.

– When Finish is clicked, the custom template closes, returning you to the analysis.

2.6.2.2. Defining Functions for the Multiple-Step Custom Template

Callbacks for wizard steps are defined in the IronPython script referenced by the extension’s XML file.
The extension PressureLossMultiple references the script pressureLoss.py.
meshingComponent1 = None
study1 = None
import1 = None
physicsDefinitionComponent1 = None
resultsEvaluationComponent1 = None
solvePhysicsComponent1 = None
physicsRegion1 = None
vectorResult1 = None
singleValueResult1 = None
results1 = None
materialAssignment1 = None
currentStep = None
clr.AddReference("Ans.UI")

def getSelectionSetsForProject():
context = __scriptingEngine__.CommandContext
project = context.Project
containers = project.GetContainers()
dataEntity = "SelectionSet"

for container in containers:

if container.Name == "Study":
try:
lockObject = context.ContainerReadLock(container)
dataReferences = project.GetDataReferencesByType(container, dataEntity)
finally:
lockObject.Dispose()
break
return dataReferences

def isValid(step, property):

if property.Value == step.Properties["InletLocation"].Value:
ExtAPI.Log.WriteWarning("Inlet and Outlet locations must be different.")
return False
return True

def importGeometry(step):
global meshingComponent1, import1, study1, results1, vectorResult1, singleValueResult1,
physicsDefinitionComponent1, resultsEvaluationComponent1, solvePhysicsComponent1, physicsRegion1,
materialAssignment1
with Transaction():
system1 = GetSystem(Name="Study")
physicsDefinitionComponent1 = Study.CreateTask( Type="Physics Definition", System=system1)
study1 = system1.GetContainer(ComponentName="Study")
physicsDefinition1 = physicsDefinitionComponent1.GetTaskObject()
physicsRegion1 = study1.CreateEntity( Type="PhysicsRegion", Association=physicsDefinition1)
solverSettings1 = study1.CreateEntity( Type="SolverSettings", Association=physicsDefinition1)
solvePhysicsComponent1 = Study.CreateTask( Type="Solve Physics", System=system1,
Input=physicsDefinitionComponent1)
solvePhysicsComponent1.Refresh()
resultsEvaluationComponent1 = Study.CreateTask( Type="Results Evaluation", System=system1,

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 43
AIM Wizards

Input=solvePhysicsComponent1)
resultsEvaluationComponent1.Refresh()
physicsDefinition1.CalculationType = "Static"
physicsRegion1.PhysicsType = "Fluid"
physicsRegion1.Location = "AllBodies()"
materialAssignment1 = study1.CreateEntity( Type="MaterialAssignment", Association=physicsDefinition1)
material1 = study1.CreateEntity( Type="Material", Association=physicsDefinition1)
material1.ImportEngineeringData(Name="Air")
materialAssignment1.Material = material1
materialAssignment1.Location = [physicsRegion1]
results1 = resultsEvaluationComponent1.GetTaskObject()
vectorResult1 = study1.CreateEntity( Type="VectorResult", Association=results1)
vectorResult1.Variable = "Velocity"
vectorResult1.DisplayText = "Velocity"
transcript1 = study1.CreateEntity( Type="Transcript", Association=physicsDefinition1)
transcript1.DisplayText = "Fluid Flow Output 1"
physicsSolutionGroup1 = Study.CreateGroup(Name="Physics Solution")
physicsSolutionGroup1.Add(Component=physicsDefinitionComponent1)
physicsSolutionGroup1.Add(Component=solvePhysicsComponent1)
meshingComponent1 = Study.CreateTask( Type="Meshing", System=system1, Output=physicsDefinitionComponent1
physicsDefinitionComponent1.Refresh()
solvePhysicsComponent1.Refresh()
resultsEvaluationComponent1.Refresh()
importComponent1 = Study.CreateTask( Type="Import", System=system1, Output=meshingComponent1)
meshingComponent1.Refresh()
physicsDefinitionComponent1.Refresh()
solvePhysicsComponent1.Refresh()
resultsEvaluationComponent1.Refresh()
import1 = importComponent1.GetTaskObject()
geometryImportSource1 = import1.AddGeometryImportSourceOperation()
geometryImportSource1.FilePath = step.Properties["geometryfile"].Value
importComponent1.Update(AllDependencies=True)
meshingComponent1.Refresh()
physicsDefinitionComponent1.Refresh()
solvePhysicsComponent1.Refresh()
resultsEvaluationComponent1.Refresh()

Study.ChangeModelSelectionContextTo(import1)

def refineMesh(step):
global meshingComponent1, import1, study1, results1, vectorResult1, physicsDefinitionComponent1, singleValue
resultsEvaluationComponent1, solvePhysicsComponent1, physicsRegion1
meshing1 = meshingComponent1.GetTaskObject()
meshing1.MeshResolution = step.Properties["MeshResolution"].Value

Study.ChangeModelSelectionContextTo(import1)

def setup(step):
global meshingComponent1, study1, results1, vectorResult1, physicsDefinitionComponent1, singleValueResult1,
resultsEvaluationComponent1, solvePhysicsComponent1, physicsRegion1
with Transaction():
meshing1 = meshingComponent1.GetTaskObject()
meshControlLocalInflation1 = study1.CreateEntity( Type="MeshControlLocalInflation", Association=meshing1
meshing1.EngineeringIntent = "FluidFlow"
AddSourceToComponentInSystem( SourceComponent=physicsDefinitionComponent1,
TargetComponent=resultsEvaluationComponent1)
resultsEvaluationComponent1.Refresh()

Study.Delete(Items=[meshControlLocalInflation1])

with Transaction():
meshingComponent1.Update(AllDependencies=True)
physicsDefinitionComponent1.Refresh()
solvePhysicsComponent1.Refresh()
resultsEvaluationComponent1.Refresh()

with Transaction():
inletBoundary1 = study1.CreateEntity( Type="InletBoundary", Association=physicsRegion1)
inlet_location = step.Properties["InletLocation"].Value.LocationSet

if inlet_location == None :
ExtAPI.Log.WriteMessage("inlet selection set does not exist")

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
44 of ANSYS, Inc. and its subsidiaries and affiliates.
 Guided Simulation Example

inletBoundary1.Location = inlet_location
inletBoundary1.Flow.Velocity.Magnitude = step.Properties["Velocity"].DisplayString

outletBoundary1 = study1.CreateEntity( Type="OutletBoundary", Association=physicsRegion1)

outlet_location = step.Properties["OutletLocation"].Value.LocationSet

if outlet_location == None :
ExtAPI.Log.WriteMessage("outlets selection set does not exist")

outletBoundary1.Location = outlet_location
outletBoundary1.Flow.Pressure.GaugeStaticPressure = step.Properties["GaugePressure"].DisplayString

wallBoundary1 = study1.CreateEntity( Type="WallBoundary", Association=physicsRegion1)

# Creation of the pressure loss expression.

singleValueResult1 = study1.CreateEntity( Type="SingleValueResult", Association=results1)
singleValueResult1.Method = "UserDefinedExpressionMethod"
singleValueResult1.Expression = "Average(Pressure, GetBoundary('@Inlet 1'), Weight='Area') -
Average(Pressure, GetBoundary('@Outlet 1'), Weight='Area')"

with Transaction():
physicsDefinitionComponent1.Update(AllDependencies=True)
solvePhysicsComponent1.Update(AllDependencies=True)
resultsEvaluationComponent1.Refresh()
resultsEvaluationComponent1.Refresh()
resultsEvaluationComponent1.Update(AllDependencies=True)

vectorResult1.Legend.Coloring = "Banded"
vectorResult1.Legend.NumberOfColors = "10"
vectorResult1.Distribution = "Mesh"
vectorResult1.Evaluate()
maximum_velocity = vectorResult1.Summary.Max
step.NextStep.Properties["MaximumVelocity"].Value = maximum_velocity.ToString()
step.NextStep.Properties["PressureLoss"].Value = singleValueResult1.Value.ToString()

def solve(step):
global meshingComponent1, study1, results1, vectorResult1, physicsDefinitionComponent1,
singleValueResult1, resultsEvaluationComponent1, solvePhysicsComponent1, physicsRegion1
with Transaction():
physicsDefinitionComponent1.Update(AllDependencies=True)
solvePhysicsComponent1.Update(AllDependencies=True)
resultsEvaluationComponent1.Refresh()
resultsEvaluationComponent1.Refresh()
resultsEvaluationComponent1.Update(AllDependencies=True)

vectorResult1.Legend.Coloring = "Banded"
vectorResult1.Legend.NumberOfColors = "10"
vectorResult1.Distribution = "Mesh"
vectorResult1.Evaluate()
maximum_velocity = vectorResult1.Summary.Max
step.NextStep.Properties["MaximumVelocity"].Value = maximum_velocity.ToString()
step.NextStep.Properties["PressureLoss"].Value = singleValueResult1.Value.ToString()

2.7. Guided Simulation Example

The supplied extension LinearBuckling contains a guided simulation (p. 5) for calculating the
linear buckling load for a geometry. The guided simulation uses UserCommands to insert in the com-
putation code snippets that instruct the MAPDL solver to perform a linear eigenvalue buckling compu-
tation after the static computation.

Note

This extension is also available as the free Linear Extension app on the ANSYS Store.

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 45
AIM Wizards

2.7.1. Creating the Guided Simulation

In the XML file for the extension LinearBuckling, the element <wizard> has the attribute Per-
sistent set to True to indicate that it is a guided simulation. This guided simulation contains three
steps.
<extension name="Linear Buckling">
<guid>d694ad22-f9de-4355-ae00-1b2ed49956d1</guid>
<author>Ansys Inc</author>
<script src=LinearBuckling.py" />
<description>Linear Buckling App</description>

<interface context="Study">
<images>images</images>
</interface>

<wizard persistent="True" name="LinearBuckling" caption="Linear Buckling" version="1" context="Study" icon="Lin

<description>Select a geometry on which to perform a Linear Buckling analysis. Calculate the Euler Buckling L

<step name="Step_1" version="0" caption="Geometry" context="Study" helpFile="help/Step_1.html">

<property control="fileopen" name="geometry" caption="Select geometry file" persistent="False" parameteriza
<callbacks>
<oncreate>createStep1</oncreate>
<onupdate>updateStep1</onupdate>
</callbacks>
</step>

<step name="Step_2" version="0" caption="Conditions" helpFile="help/Step2.html">

<property control="scoping" name="support" caption="Select support Location" persistent="False" parameteriz
<property control="scoping" name="force" caption="Select force location" persistent="False" parameterizable
<property name="YoungsModulus" caption="Young's Modulus" control="float" unit="Pressure" default="200000000
<property name="PoissonRatio" caption="Poisson's Ratio" control="float" unit="None" default="0.3" />
<callbacks>
<onupdate>updateStep2</onupdate>
<onrefresh>refreshStep2</onrefresh>
</callbacks>
</step>

<step name="Step_3" version="0" caption="Buckling Load" helpFile="help/Step3.html">

<property control="float" name="bucklingLoad" caption="Buckling Load" persistent="False" parameterizable="F
<callbacks>
<onupdate>updateStep3</onupdate>
<onrefresh>refreshStep3</onrefresh>
</callbacks>
</step>
</wizard>
</extension>

Step 1: Geometry Import and Problem Setup

The first step imports the geometry and sets up the structural simulation, including the code snippets
for the computation of the buckling load. The callbacks <oncreate> and <onupdate> are used to
differentiate the actions that are needed the first time that the step is updated from those actions that
are needed in subsequent updates.

• The callback <oncreate> is named createStep1. It creates the geometry task, executes the import
of the geometry, and proceeds to create all required tasks for the static structural computation. It only
executes the update of the geometry task because the user input gathered in step 2 is needed for the
structural computation. This callback also executes the following actions:

– Adds via UserCommands the custom code snippets for computation of the buckling load.

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
46 of ANSYS, Inc. and its subsidiaries and affiliates.
 Guided Simulation Example

– Creates a contour result object for displaying displacement magnitude. This result object is to contain
the displacement that describes the shape of the first buckling mode.

• The callback <onupdate> is named updateStep1. It is invoked after the callback <oncreate>
has been executed once. In this callback, a new geometry file is imported. Any contact created for the
previous geometry is also deleted because it is generally not applicable to the new geometry.

Step 2: User Data Collection

In the second step, data needed for the computations is collected. The inputs include:

• Location of the support for the structure

• Location of the force applied to the structure for which a buckling load estimation is wanted

• Material properties (Young’s modulus and Poisson ratio)

Step 2 contains a refresh callback and an update callback:

• The callback <refresh> is named refreshStep2. It is used to display the force that was applied
in the first step. Because the first step can be visited before it is updated, the callback ignores any error
generated if the force is not yet defined.

• The callback <update> is named updateStep2. It gathers the data entered for support, force, and
material properties and proceeds to update the mesh, physics (including the custom snippets), and
result task. At the end of the update, the callback retrieves the information about the buckling load
that was requested as part of the custom code snippet. This information is used to populate the result
shown in the third step.

Step 3: Result Display and Report Export

The third step also contains a refresh callback and an update callback:

• The callback <refresh> is named refreshStep3. It is used to display the contour of the displace-
ment magnitude for the deformation of the first buckling mode, which was calculated in the second
step. Because the third step can be visited before the second step is updated, the callback ignores
any error generated if the contour is not yet defined.

• The callback <update> is named updateStep3. It is the last action performed for this guided sim-
ulation. It simply exports a report containing a summary of the computation.

2.7.2. Defining Functions for the Guided Simulation

Callbacks for wizard steps are defined in the IronPython script referenced by the extension’s XML file.
The extension Linear Buckling references the script LinearBuckling.py.
def updateStep1(step):
#This function is the update that is invoked after the first update. It is used for replacing the original ge
#Information about the geometry task is retrieved by step attributes
geometryModelingComponent = getCompomentByName(step.Attributes["geometryModelingComponent"])
modeling1 = geometryModelingComponent.GetTaskObject()
modeling1.SetImportPath(FilePath=step.Properties["geometry"].ValueString)
geometryModelingComponent.Update()
StudyUI.SetSelectionTo(modeling1)
#Instructs the user interface to display the new geometry
model = Study.GetModelFromObject(Object = modeling1)

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 47
AIM Wizards

Study.SetCurrentModelForExtension(Model = model)
#Removes any contact generated for the previous geometry since they could be invalid for the new geometry
physicsDefinitionTask = getCompomentByName(step.Attributes["physicsDefinitionComponentName"]).GetTask()
with Transaction():
Study.Delete(Items=physicsDefinitionTask.GetAllObjectsOfType(Type="Contact"))

def resetStep1(step):
pass

def createStep1(step):
#This function is the update function that is invoked the first time update is invoked
#It imports a geometry, sets up the information for a structural computation and adds custom snippets for lin
system1 = GetSystem(Name="Study")
geometryModelingComponent1 = Study.CreateTask(
Type="Geometry Modeling",
System=system1)
step.Attributes["geometryModelingComponent"] = geometryModelingComponent1.Name
modeling1 = geometryModelingComponent1.GetTaskObject()
modeling1.SetImportPath(FilePath=step.Properties["geometry"].ValueString)
meshingComponent1 = Study.CreateTask(
Type="Meshing",
System=system1,
Input=geometryModelingComponent1)
meshing1 = meshingComponent1.GetTaskObject()
meshing1.EngineeringIntent = "StructuralOrThermalOrElectricConduction"
meshingComponent1.Refresh()
physicsDefinitionComponent1 = Study.CreateTask(
Type="Physics Definition",
System=system1,
Input=meshingComponent1)
step.Attributes["physicsDefinitionComponentName"] = physicsDefinitionComponent1.Name
physicsDefinition1 = physicsDefinitionComponent1.GetTaskObject()
physicsDefinition1.CalculationType = "Static"
study1 = system1.GetContainer(ComponentName="Study")
solverSettings1 = study1.CreateEntity(
Type="SolverSettings",
Association=physicsDefinition1)
solvePhysicsComponent1 = Study.CreateTask(
Type="Solve Physics",
System=system1,
Input=physicsDefinitionComponent1)
solvePhysicsComponent1.Refresh()
physicsSolutionGroup1 = Study.CreateGroup(Name="Physics Solution")
physicsSolutionGroup1.Add(Component=physicsDefinitionComponent1)
physicsSolutionGroup1.Add(Component=solvePhysicsComponent1)
physicsSolutionGroup1.DisplayText = "Buckling"
physicsRegion1 = study1.CreateEntity(
Type="PhysicsRegion",
Association=physicsDefinition1)
physicsRegion1.PhysicsType = "Structural"
physicsRegion1.Location = "AllBodies()"
physicsRegion1.DisplayText = "LinearBuckling"
materialAssignment1 = study1.CreateEntity(
Type="MaterialAssignment",
Association=physicsDefinition1)
material1 = study1.CreateEntity(
Type="Material",
Association=physicsDefinition1)
step.Attributes["materialName"] = material1.Name
material1.ImportEngineeringData(Name="Structural Steel")
material1.DisplayText = "Material"
materialAssignment1.Material = material1
materialAssignment1.Location = [physicsRegion1]
interfaceGenerator1 = study1.CreateEntity(
Type="InterfaceGenerator",
Association=physicsDefinition1)
transcript1 = study1.CreateEntity(
Type="Transcript",
Association=physicsDefinition1)
transcript1.DisplayText = "Structural Output 1"
resultsEvaluationComponent1 = Study.CreateTask(
Type="Results Evaluation",

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
48 of ANSYS, Inc. and its subsidiaries and affiliates.
 Guided Simulation Example

System=system1,
Input=solvePhysicsComponent1)
AddSourceToComponentInSystem(
SourceComponent=physicsDefinitionComponent1,
TargetComponent=resultsEvaluationComponent1)
resultsEvaluationComponent1.Refresh()
results1 = resultsEvaluationComponent1.GetTaskObject()
contourResult1 = study1.CreateEntity(
Type="ContourResult",
Association=results1)
contourResult1.Variable = "Displacement.mag"
contourResult1.DisplayText = "Buckling Mode 1"
step.Attributes["bucklingDisplacementContourName"] = contourResult1.Name
geometryModelingComponent1.Update(AllDependencies=True)
model = Study.GetModelFromObject(Object = modeling1)
Study.SetCurrentModelForExtension(Model = model)
interfaceGenerator1.GenerateInteractions()

#The support and force are created in this step but their location is defined in the following step
#Step attributes are used to retrieve the created support and force
support1 = study1.CreateEntity(
Type="Support",
Association=physicsDefinition1)
step.Attributes["supportName"] = support1.Name
force1 = study1.CreateEntity(
Type="Force",
Association=physicsDefinition1)
step.Attributes["forceName"] = force1.Name
force1.Vector.VectorByMagnitudeAndDirection.Magnitude = "1 [N]"
force1.Vector.VectorByMagnitudeAndDirection.ReverseDirection = "True"

#Creates user command to executed custom MAPDL code that performs a linear
#eigenvalue buckling computation
userCommands1 = study1.CreateEntity(
Type="UserCommands",
Association=physicsDefinition1)
userCommands1.AddCodeSnippet(
SectionPath="Solve/Loadcase/JustBeforeSolveSection",
Commands="""solve
finish
/assign,rstp,file,rst
/solu
antype,,restart,,,perturb
perturb,buckle,,CURRENT,ALLKEEP
solve,elform
bucopt,lanb,1,,,center
outres,erase
outres,all,all""")
#Creates user command to executed custom MAPDL code that retrieves
#the buckling load for the eigenvalue buckling computation
userCommands1.AddCodeSnippet(
SectionPath="PostProcessingSection",
Commands=r"""/OUT,..\..\..\..\user_files\myloadfactors,txt
*GET,FREQ,MODE,1,FREQ
/output""")

#Displays the model at the end of the update

StudyUI.SetSelectionTo(modeling1)

def updateStep2(step):

system1 = GetSystem(Name="Study")
study1 = system1.GetContainer(ComponentName="Study")

#Retrieves the support and force and applies the user specified location
support1 = study1.GetSupport(Name=getStepByName(step, "Step_1").Attributes["supportName"])
support1.Location = step.Properties["support"].Value.LocationSet
force1 = study1.GetForce(Name=getStepByName(step, "Step_1").Attributes["forceName"])
force1.Location = step.Properties["force"].Value.LocationSet

#Applies material properties to the user defined material

material1 = study1.GetMaterial(Name=getStepByName(step, "Step_1").Attributes["materialName"])

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 49
AIM Wizards

material1.Solid.IsotropicElasticity.Magnitude.YoungsModulus = step.Properties["YoungsModulus"].ValueString
material1.Solid.IsotropicElasticity.Magnitude.PoissonsRatio = step.Properties["PoissonRatio"].ValueString

#Solution
resultsEvaluationComponent1 = system1.GetComponent(Name="Results Evaluation")
resultsEvaluationComponent1.Update(AllDependencies=True)
study1 = system1.GetContainer(ComponentName="Study")
contourResult1 = study1.GetContourResult(Name=getStepByName(step, "Step_1").Attributes["bucklingDisplacementC
contourResult1.Evaluate()

# get loadfactor from the file created by the custom command

userDir = GetProjectFile().split(".wbpj")[0] + "_files"
file = userDir + "\\user_files\\" + "myloadfactors"
frequencyFile = file +".txt"
f = open(frequencyFile, 'r')
text = f.readline()
text = f.readline()
force1 = text.split("VALUE=")[1].lstrip() + " [N]"

#Finds the results step and assigns the value of the computed buckling load
s = step.NextStep
s.Properties["bucklingLoad"].Value = force1

#Plots the displacement results

StudyUI.SetSelectionTo(contourResult1)

def refreshStep2(step):

system1 = GetSystem(Name="Study")
study1 = system1.GetContainer(ComponentName="Study")
#If the force is defined, it is set to be displayed in the UI
try:
force1 = study1.GetForce(Name=getStepByName(step, "Step_1").Attributes["forceName"])
StudyUI.SetSelectionTo(force1)
except:
force1 = None

def updateStep3(step):

clr.AddReference("Ans.UI.Toolkit")
clr.AddReference("Ans.UI.Toolkit.Base")
from Ansys.UI.Toolkit import *

# generates report
userDir = GetProjectFile().split(".wbpj")[0] + "_files"
file = userDir + "\\user_files\\" + "eulerbuckling.html"
ExportReport(FilePath=file)
MessageBox.Show("Report written to user_files: "+file)

def refreshStep3(step):

system1 = GetSystem(Name="Study")
study1 = system1.GetContainer(ComponentName="Study")
#If the displacement contour is defined, it is set to be displayed in the UI
try:
contourResult1 = study1.GetContourResult(Name=getStepByName(step, "Step_1").Attributes["bucklingDisplacem
StudyUI.SetSelectionTo(contourResult1)
except:
contourResult1 = None

pass

# helper functions

def getCompomentByName(componentName):
for c in GetSystem(Name="Study").Components:
if c.Name == componentName:
return c
return None

def getStepByName(currentStep, stepName):

for step in currentStep.Wizard.Steps:

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
50 of ANSYS, Inc. and its subsidiaries and affiliates.
 AIM Project Wizards

if step.Key == stepName:
return step.Value
return None

2.8. AIM Project Wizards

To create a project wizard for AIM, in the extension's XML file, you add the element <wizard> and
set the attribute context to Project. The XML for defining an AIM project wizard is the same as the
XML for defining a Workbench project wizard. However, because the layout for an AIM wizard is pre-
defined, you cannot define the element <uidefinition> to customize the wizard interface.
2.8.1. Creating the AIM Project Wizard
2.8.2. Defining Functions for the AIM Project Wizard
2.8.3. Reviewing AIM Project Wizard Results

2.8.1. Creating the AIM Project Wizard

The supplied extension PressureLoss contains an AIM project wizard for calculating the maximum
velocity and pressure loss for a CFD system with one inlet and three outlets. The XML file follows. In
the element <wizard>, the attribute name is set to PressureLoss. The attribute context is set
to Project.
<extension version="1" name="PressureLoss" icon="images\loss.png">
<guid shortid="PressureLoss">74182c0a-16ea-4169-8a55-00bad98afb6c</guid>
<author>ANSYS Inc.</author>
<description>Demonstration of a pressure loss in AIM.</description>

<script src="pressureLoss.py" />

<interface context="Project">
<images>images</images>
</interface>

<wizard name="PressureLoss" version="1" context="Project" icon="loss">

<description>This wizard is for demonstration of ACT wizard capability in AIM.</description>

<step name="Step1" caption="Import the geometry" version="1" context="Project" HelpFile="help/geometry.html">

<description>Import the geometry file and create the workflow.</description>

<callbacks>
<onupdate>importGeometry</onupdate>
</callbacks>

<property name="geometryfile" caption="geometry file" control="fileopen" default="E:\Geometry\TubeSelection

</step>

<step name="Step2" caption="Refine the mesh" version="1" context="Project" HelpFile="help/mesh.html">

<description>Refine the mesh from Low to High.</description>

<callbacks>
<onupdate>refineMesh</onupdate>
</callbacks>

<property name="MeshResolution" caption="mesh resolution" control="integer" default="1"/>

</step>

<step name="Step3" caption="Define the loads" version="1" context="Project" HelpFile="help/loads.html">

<description>Specify the loads to applied on the geometry.</description>

<callbacks>
<onrefresh>initLocations</onrefresh>
<onupdate>setup</onupdate>
</callbacks>

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 51
AIM Wizards

<propertygroup name="Inlet" caption="Inlet">

<property name="Velocity" caption="Velocity" control="float" unit="Velocity" default="0.1 [m s^-1]"/>
<property name="InletLocation" caption="InletLocation" control="select" />
</propertygroup>

<propertygroup name="Outlet" caption="Outlet">

<property name="GaugePressure" caption="Gauge Pressure" control="float" unit="Pressure" default="0 [Pa]"/
<property name="OutletLocation" caption="OutletLocation" control="select" >
<callbacks>
<isvalid >isValid</isvalid>
</callbacks>
</property>
</propertygroup>
</step>

<step name="Step4" caption="Export the maximum velocity" version="1" context="Project" HelpFile="help/result

<description>Here we are just exposing the value of the maximum velocity and the pressure loss.</descripti

<property name="MaximumVelocity" caption="Maximum Velocity" control="float" unit="Velocity" readonly = "Tr

<property name="PressureLoss" caption="Pressure Loss" control="float" unit="Pressure" readonly = "True"/>
</step>
</wizard>

</extension>

Step Definition

You use the element <step> to define a step in the wizard. Required attributes are name and version.
The optional attribute caption sets the display text for the step. You only need to set the attribute
context if the context for a step differs from the context for the wizard. All four steps in the wizard
PressureLoss are executed from the Project tab in AIM.

Additional optional attributes can be defined for steps. For example, you can use the attribute Help-
File to specify an HTML file with the custom help to display for the step. In this example, the help
provided for each step indicates where each property is displayed in the Study panel.

Callback Definition

Each step defined in the XML file can have multiple callbacks invoking functions defined in the script.
You use the element <callbacks> to define the callbacks for the step. Each callback receives the
current step as a method argument.

A summary follows of the callbacks for steps in the wizard PressureLoss:

• Step1: The callback <onupdate> executes the function importGeometry. This step creates the
CFD workflow, importing and then generating the specified geometry when Next is clicked.

• Step2: The callback <onupdate> executes the function refineMesh. This step allows the mesh
resolution to be specified and the mesh refined accordingly when Next is clicked.

• Step3: The callback <onrefresh> executes the function initLocations. The callback <onup-
date> executes the function setup. This step provides for specifying the loads to apply to the inlet
and outlet. You select a location and specify the velocity for the input and the gauge pressure for the
outlet. The callback <isvalid> on the property OutletLocation executes the action isValid,
validating the value selected for the outlet location.

• Step4: No callbacks are required. This step takes the value calculated for the property Calculated-
Maximum and populates it to the field Calculated maximum for the object Velocity.

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
52 of ANSYS, Inc. and its subsidiaries and affiliates.
 AIM Project Wizards

2.8.2. Defining Functions for the AIM Project Wizard

The script pressureLoss.py defines the functions executed by the callbacks.
meshingComponent1 = None
study1 = None
physicsDefinitionComponent1 = None
resultsEvaluationComponent1 = None
solvePhysicsComponent1 = None
physicsRegion1 = None
vectorResult1 = None
singleValueResult1 = None
results1 = None
materialAssignment1 = None
currentStep = None
clr.AddReference("Ans.UI")

def getSelectionSetsForProject():
context = __scriptingEngine__.CommandContext
project = context.Project
containers = project.GetContainers()
dataEntity = "SelectionSet"

for container in containers:

if container.Name == "Study":
try:
lockObject = context.ContainerReadLock(container)
dataReferences = project.GetDataReferencesByType(container, dataEntity)
finally:
lockObject.Dispose()
break
return dataReferences

def initLocations(step):
list = getSelectionSetsForProject()
propIn = step.Properties["Inlet/InletLocation"]
propIn.Options.Clear()
propOut = step.Properties["Outlet/OutletLocation"]
propOut.Options.Clear()
for sel in list:
ExtAPI.Log.WriteMessage("OPTION: "+sel.DisplayText)
propIn.Options.Add(sel.DisplayText)
propOut.Options.Add(sel.DisplayText)
comp = step.UserInterface.GetComponent("Properties")
comp.UpdateData()
comp.Refresh()

def isValid(step, property):

if property.Value == step.Properties["Inlet/InletLocation"].Value:
ExtAPI.Log.WriteWarning("Inlet and Outlet locations must be different.")
return False
return True

def importGeometry(step):
global meshingComponent1, study1, results1, vectorResult1, singleValueResult1, physicsDefinitionComponent1, re
with Transaction():
system1 = GetSystem(Name="Study")
physicsDefinitionComponent1 = Study.CreateTask( Type="Physics Definition", System=system1)
study1 = system1.GetContainer(ComponentName="Study")
physicsDefinition1 = physicsDefinitionComponent1.GetTaskObject()
physicsRegion1 = study1.CreateEntity( Type="PhysicsRegion", Association=physicsDefinition1)
solverSettings1 = study1.CreateEntity( Type="SolverSettings", Association=physicsDefinition1)
solvePhysicsComponent1 = Study.CreateTask( Type="Solve Physics", System=system1, Input=physicsDefinitionCom
solvePhysicsComponent1.Refresh()
resultsEvaluationComponent1 = Study.CreateTask( Type="Results Evaluation", System=system1, Input=solvePhysi
resultsEvaluationComponent1.Refresh()
physicsDefinition1.CalculationType = "Static"
physicsRegion1.PhysicsType = "Fluid"
physicsRegion1.Location = "AllBodies()"
materialAssignment1 = study1.CreateEntity( Type="MaterialAssignment", Association=physicsDefinition1)
material1 = study1.CreateEntity( Type="Material", Association=physicsDefinition1)

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 53
AIM Wizards

material1.ImportEngineeringData(Name="Air")
materialAssignment1.Material = material1

materialAssignment1.Location = [physicsRegion1]
results1 = resultsEvaluationComponent1.GetTaskObject()
vectorResult1 = study1.CreateEntity( Type="VectorResult", Association=results1)
vectorResult1.Variable = "Velocity"
vectorResult1.DisplayText = "Velocity"
transcript1 = study1.CreateEntity( Type="Transcript", Association=physicsDefinition1)
transcript1.DisplayText = "Fluid Flow Output 1"
physicsSolutionGroup1 = Study.CreateGroup(Name="Physics Solution")
physicsSolutionGroup1.Add(Component=physicsDefinitionComponent1)
physicsSolutionGroup1.Add(Component=solvePhysicsComponent1)
meshingComponent1 = Study.CreateTask( Type="Meshing", System=system1, Output=physicsDefinitionComponent1)
physicsDefinitionComponent1.Refresh()
solvePhysicsComponent1.Refresh()
resultsEvaluationComponent1.Refresh()
importComponent1 = Study.CreateTask( Type="Import", System=system1, Output=meshingComponent1)
meshingComponent1.Refresh()
physicsDefinitionComponent1.Refresh()
solvePhysicsComponent1.Refresh()
resultsEvaluationComponent1.Refresh()
import1 = importComponent1.GetTaskObject()
geometryImportSource1 = import1.AddGeometryImportSourceOperation()
geometryImportSource1.FilePath = step.Properties["geometryfile"].Value
importComponent1.Update(AllDependencies=True)
meshingComponent1.Refresh()
physicsDefinitionComponent1.Refresh()
solvePhysicsComponent1.Refresh()
resultsEvaluationComponent1.Refresh()

def refineMesh(step):
global meshingComponent1, study1, results1, vectorResult1, physicsDefinitionComponent1, singleValueResult1, res
meshing1 = meshingComponent1.GetTaskObject()
meshing1.MeshResolution = step.Properties["MeshResolution"].Value

def setup(step):
global meshingComponent1, study1, results1, vectorResult1, physicsDefinitionComponent1, singleValueResult1, res
with Transaction():
meshing1 = meshingComponent1.GetTaskObject()
meshControlLocalInflation1 = study1.CreateEntity( Type="MeshControlLocalInflation", Association=meshing1)
meshing1.EngineeringIntent = "FluidFlow"
AddSourceToComponentInSystem( SourceComponent=physicsDefinitionComponent1, TargetComponent=resultsEvaluatio
resultsEvaluationComponent1.Refresh()
#meshControlLocalInflation1.Location = ["FACE8", "FACE2", "FACE6"]
Study.Delete(Items=[meshControlLocalInflation1])
with Transaction():
meshingComponent1.Update(AllDependencies=True)
physicsDefinitionComponent1.Refresh()
solvePhysicsComponent1.Refresh()
resultsEvaluationComponent1.Refresh()

with Transaction():
inletBoundary1 = study1.CreateEntity( Type="InletBoundary", Association=physicsRegion1)

inlet_location = step.Properties["Inlet/InletLocation"].Value
ExtAPI.Log.WriteMessage("my inlet location property value is : " + inlet_location)
inlet_selection_set = None
selection_sets = getSelectionSetsForProject()
for selection_set in selection_sets:
if selection_set.DisplayText == inlet_location:
inlet_selection_set = selection_set
if inlet_selection_set == None :
ExtAPI.Log.WriteMessage("inlet selection set does not exist")

inletBoundary1.Location = [inlet_selection_set]

inletBoundary1.Flow.Velocity.Magnitude = step.Properties["Inlet/Velocity"].DisplayString

outletBoundary1 = study1.CreateEntity( Type="OutletBoundary", Association=physicsRegion1)

outlet_location = step.Properties["Outlet/OutletLocation"].Value

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
54 of ANSYS, Inc. and its subsidiaries and affiliates.
 AIM Project Wizards

outlet_selection_set = None
selection_sets = getSelectionSetsForProject()
for selection_set in selection_sets:
if selection_set.DisplayText == outlet_location:
outlet_selection_set = selection_set
if outlet_selection_set == None :
ExtAPI.Log.WriteMessage("outlets selection set does not exist")

outletBoundary1.Location = [outlet_selection_set]
outletBoundary1.Flow.Pressure.GaugeStaticPressure = step.Properties["Outlet/GaugePressure"].DisplayString

wallBoundary1 = study1.CreateEntity( Type="WallBoundary", Association=physicsRegion1)

# Creation of the pressure loss expression.

singleValueResult1 = study1.CreateEntity( Type="SingleValueResult", Association=results1)
singleValueResult1.Method = "UserDefinedExpressionMethod"
singleValueResult1.Expression = "Average(Pressure, GetBoundary('@Inlet 1'), Weight='Area') - Average(Pressu

with Transaction():
physicsDefinitionComponent1.Update(AllDependencies=True)
solvePhysicsComponent1.Update(AllDependencies=True)
resultsEvaluationComponent1.Refresh()
resultsEvaluationComponent1.Refresh()
resultsEvaluationComponent1.Update(AllDependencies=True)

vectorResult1.Legend.Coloring = "Banded"
vectorResult1.Legend.NumberOfColors = "10"
vectorResult1.Distribution = "Mesh"
vectorResult1.Evaluate()
maximum_velocity = vectorResult1.Summary.Max
step.NextStep.Properties["MaximumVelocity"].Value = maximum_velocity.ToString()
step.NextStep.Properties["PressureLoss"].Value = singleValueResult1.Value.ToString()

def solve(step):
global meshingComponent1, study1, results1, vectorResult1, physicsDefinitionComponent1, singleValueResult1, res
with Transaction():
physicsDefinitionComponent1.Update(AllDependencies=True)
solvePhysicsComponent1.Update(AllDependencies=True)
resultsEvaluationComponent1.Refresh()
resultsEvaluationComponent1.Refresh()
resultsEvaluationComponent1.Update(AllDependencies=True)

vectorResult1.Legend.Coloring = "Banded"
vectorResult1.Legend.NumberOfColors = "10"
vectorResult1.Distribution = "Mesh"
vectorResult1.Evaluate()
maximum_velocity = vectorResult1.Summary.Max
step.NextStep.Properties["MaximumVelocity"].Value = maximum_velocity.ToString()
step.NextStep.Properties["PressureLoss"].Value = singleValueResult1.Value.ToString()

2.8.3. Reviewing AIM Project Wizard Results

After you install and load the extension PressureLoss in AIM, to start the project wizard, you must
use the Wizards launcher, which is available when you click Launch Wizards on the ACT Start Page.

When the project wizard PressureLoss executes, the final page shows the calculated Maximum
Velocity. The custom help, which the help panel displays, explains where the result is shown.

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 55
AIM Wizards

Clicking Finish on the final wizard page returns you to the ACT Start Page.

In the Study panel, you can see that the project wizard created the workflow in AIM and then auto-
matically executed the steps.

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
56 of ANSYS, Inc. and its subsidiaries and affiliates.
 AIM Project Wizards

You can open the Results task to view the final results obtained by this simulation.

Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 57
 Release 2019 R3 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
58 of ANSYS, Inc. and its subsidiaries and affiliates.