This section describes customization for ANSYS Mechanical only as this targeted product needs to expose preprocessing features natively.
Thus far the discussion has been focused on extending the user interface by adding toolbars. This section discusses how to use toolbars to perform meaningful operations such as adding a preprocessing feature to Mechanical. The example used in the discussion is defined in the extension DemoLoad. This extension, which adds a generic load to a project, is for demonstration purposes only.
The XML extension definition file DemoLoad.xml follows. As in
previous examples, this file first defines the extension using the attributes
version and name. The path to the
IronPython script main.py is specified by the
<script> block. The definition of the toolbar and
the buttons is done in the <interface> block. The
callback function CreateDemoLoad is used to create and add
the load to the simulation environment.
<extension version="1" minorversion="0" name="DemoLoad">
<guid shortid="DemoLoad">7dfd2b34-dfe1-469d-b244-1c7e5c222e54</guid>
<script src="main.py" />
<interface context="Mechanical">
<images>images</images>
<toolbar name="Loads" caption="Loads">
<entry name="DemoLoad" icon="tload">
<callbacks>
<onclick>CreateDemoLoad</onclick>
</callbacks>
</entry>
</toolbar>
</interface>
<simdata context="Mechanical">
<load name="DemoLoad" version="1" caption="DemoLoad" icon="tload" color="#00FFFF">
<callbacks>
<getnodalvaluesfordisplay>GetNodalValuesForDisplay_DL</getnodalvaluesfordisplay>
<getprecommands>GetPreCommands_DL</getprecommands>
<getsolvecommands order="1">GetSolveCommands_DL</getsolvecommands>
</callbacks>
<property name="Geometry" caption="Geometry" control="scoping">
<attributes selection_filter="edge" />
</property>
<property name="Text" caption="Text" control="text"></property>
<property name="SelectStatic" caption="Select (static)" control="select">
<attributes options="Option 1,Option 2,Option 3" />
</property>
<property name="SelectDynamic" caption="Select (dynamic)" control="select">
<callbacks>
<onactivate>StringOptions_DL</onactivate>
</callbacks>
</property>
<property name="Double" caption="Double" unit="Length" control="float"
default="1 [m]"></property>
</load>
</simdata>
</extension>The definition of the load is encapsulated in the
<simdata> block. The attributes in the child
<load> block provide the name, version, caption,
icon, and color that apply to this load. The attribute color
is defined in a hexadecimal format. This color is used to contrast the load when it
is displayed on the model. Its child <callbacks> block
encapsulates three callbacks:
<getnodalvaluesfordisplay>,
<getprecommands>, and
<getsolvecommands>.
The callback <getnodalvaluesfordisplay>
specifies the name of the function that is invoked when the load is
displayed in the product.
The callback <getprecommands> controls
where the specific solver commands are inserted in the solver input
file. This callback inserts the solver commands before the standard
loads and boundary conditions defined in the product. For the ANSYS
solver, the new commands are inserted in the context of the /PREP7
preprocessor after the mesh has been written.
The callback <getsolvecommands> specifies
the name of the function that is invoked when the solver input file is
generated by the product. Consequently, the related function is
responsible for generating the APDL commands that describe the load
within the ANSYS input file. When the callback
<getsolvecommands> is invoked, the solver
commands are inserted into the solver input file just before the SOLVE
command.
In the callback definition, you can define the properties to apply to the actual definition of the load. These properties are displayed in the Details view of Mechanical, where the user provides the necessary values to complete the load definition. In the IronPython script, you see how the load's properties can be retrieved and modified.
The following figure shows that each property defined above appears in the Details view with the corresponding names and types of interface control.
The two properties, Select (static) and Select
(dynamic), have their attribute control set to
select. The first property populates the list of options
from the XML extension definition file, while the second one defines the callback
<onactivate>. This callback, which is called when
the control is activated, populates the available options for the property. This
second approach provides full control of the options to expose in the drop-down menu
and makes the list of options dependent on the current status of the project. Many
different situations that can impact the content of the list of options can be
addressed, as long as they are implemented in the callback
<onactivate>.
The next property, Double, does not require the definition
of one specific callback. Instead, the XML file introduces a physical quantity
dependency with the optoin unit. This option specifies that
this property is consistent with a length. In addition, a default value of
1 [m] is introduced with the option
default. This default value is exposed in the
Details view each time a new load is created.
The IronPython script main.py for the extension DemoLoad follows.
import os
def init(context):
ExtAPI.Log.WriteMessage("Init DemoLoads...")
def CreateDemoLoad(analysis):
analysis.CreateLoadObject("DemoLoad")
def StringOptions_DL(load,prop):
prop.ClearOptions()
prop.AddOption("X")
prop.AddOption("Y")
prop.AddOption("Z")
def GetPreCommands_DL(load, stream):
stream.Write("/COM, **************************************************" + "\n")
stream.Write("/COM, Load properties from DemoLoad getprecommands event" + "\n")
stream.Write("/COM, Text Property = " + load.Properties["Text"].ValueString + "\n")
stream.Write("/COM, SelectDynamic Property = " + load.Properties["SelectDynamic"].ValueString + "\n")
stream.Write("/COM, SelectStatic Property = " + load.Properties["SelectStatic"].ValueString + "\n")
stream.Write("/COM, Double Property = " + load.Properties["Double"].ValueString + "\n")
stream.Write("/COM, **************************************************" + "\n")
def GetSolveCommands_DL(load, stream):
stream.Write("/COM, **************************************************" + "\n")
stream.Write("/COM, Load properties from DemoLoad getsolvecommands event" + "\n")
stream.Write("/COM, Text Property = " + load.Properties["Text"].ValueString + "\n")
stream.Write("/COM, SelectDynamic Property = " + load.Properties["SelectDynamic"].ValueString + "\n")
stream.Write("/COM, SelectStatic Property = " + load.Properties["SelectStatic"].ValueString + "\n")
stream.Write("/COM, Double Property = " + load.Properties["Double"].ValueString + "\n")
stream.Write("/COM, **************************************************" + "\n")
def GetNodalValuesForDisplay_DL(load, nodeIds):
dval = load.Properties["Double"].Value
coordselect = load.Properties["SelectDynamic"].ValueString
mesh = load.Analysis.MeshData
values = []
for id in nodeIds:
node = mesh.NodeById(id)
dispval = float(0.0)
if coordselect == "X":
dispval = node.X * float(dval)
elif coordselect == "Y":
dispval = node.Y * float(dval)
elif coordselect == "Z":
dispval = node.Z * float(dval)
else:
dispval = float(0.0)
values.Add(dispval)
return valuesThe functions GetNodalValuesForDisplay_DL and
GetSolveCommands_DL are critical to the behavior and
application of the load. GetNodalValuesForDisplay_DL is
called each time the graphics is refreshed. The required input arguments are
load and nodeIds, where
load is the load object for this load and
nodeIds is a list of node identifiers.
In this example, load.Properties["Double"].Value queries
for the "Double" property value. The argument
nodeIds contain a list of node numbers on which one value
has to be returned by the function. For every node in the list, the value of the
property "Double" is assigned in the values array
representing the output of the function. This output is subsequently treated by the
graphics engine of the product so that the visualization on the FE model is
available.
GetSolveCommands is intentionally simplified for this
example. The prototype of this function is made of two input arguments, the load
object and the filename in which the new specific solver commands are written. The
output file is only a temporary file. The content is rewritten in the final solver
input file to ensure that the specific commands related to the customized load are
merged with all the other commands already defined by the standard features of the
product.
You can also create a specific set of context menu options. These options use the
property Action.
Actions are defined inside the <callbacks> block for
the load.
<callbacks>
<ongenerate>generate</ongenerate>
<oncleardata>clearData</oncleardata>
<action name="a1" caption="Action 1" icon="update">action1 </action>
<action name="a2" caption="Action 2" icon="update">action2 </action>
</callbacks>The <action> block takes three attributes:
A name to identify the action.
A caption to display in the context menu.
The name of the image file to display as the icon. You must place the BMP
file that Mechanical requires in the images directory
specified in the extension's XML file.
The <action> block defines the name of the function
that is called when the user selects the associated context menu option.
The following figure shows the result of the declaration. There are now two additional context menu items, and .
As illustrated, you can also add a context menu option. This option derives from the standard action provided by Mechanical. For that reason, the declaration of this particular option differs from the declaration of the options and . This option is always associated with the option.
These options allow you to create a load that can mimic a standard imported load. The callback associated with the option replaces the standard function integrated in Mechanical.
The feature is activated when you define the callback
<ongenerate> for the load.
The callback <ongenerate> is invoked each time the
context menu option is selected. It is also
invoked during a solve if the state of the load is set to "not solved."
As for the standard imported load object, the callback
<ongenerate> is called only if the mesh is already
generated.
<callbacks>
<ongenerate>generate</ongenerate>
<oncleardata>clearData</oncleardata>
<action name="a1" caption="Action 1" icon="update">action1 </action>
<action name="a2" caption="Action 2" icon="update">action2 </action>
</callbacks>The associated IronPython code looks like this:
def generate(load, fct):
pct = 0
fct(pct,"Generating data...")
propEx = load.PropertyByName("Expression")
exp = propEx.Value
if exp=="":
return False
try:
vexp = compile(exp,'','eval')
except:
return False
values = SerializableDictionary[int,float]()
nodeIds = []
propGeo = load.PropertyByName("Geometry")
refIds = propGeo.Value
mesh = ExtAPI.DataModel.MeshDataByName("Global")
for refId in refIds:
meshRegion = mesh.MeshRegionById(refId)
nodeIds += meshRegion.NodeIds
nodeIds = list(set(nodeIds))
for i in range(0,nodeIds.Count):
id = nodeIds[i]
node = mesh.NodeById(id)
x = node.X
y = node.Y
z = node.Z
v = 0.
try:
v = eval(vexp)
finally:
values.Add(id,v)
new_pct = (int)((i*100.)/nodeIds.Count)
if new_pct!=pct:
pct = new_pct
stopped = fct(pct,"Generating data...")
if stopped:
return False
propEx.SetAttributeValue("Values",values)
fct(100,"Generating data...")
return True
def clearData(load):
ExtAPI.Log.WriteMessage("ClearData: "+load.Caption)
propEx = load.PropertyByName("Expression")
propEx.SetAttributeValue("Values",None)The callback <ongenerate> takes two arguments: the
load object and a function to manage a progress bar. The function also takes two
arguments: the message to display and the value (between 0 and 100) of the progress
bar.
During the process, the generated data is stored using an attribute on the
property Expression. For more information, see Storing Data in Your Extension.
The callback <oncleardata> takes one argument: the
load object. This callback is invoked each time the mesh is cleaned or when the
context menu option is
selected.