The extension DataSquares demonstrates:
The use of custom task properties to integrate an external application
The specification that the defined task should be submitted via ANSYS Remote Solve Manager (RSM) for remote job execution
Driven by the custom task properties defined in the XML extension definition file, this external application squares the value of an input number, which is displayed in the Parameter Set bar. Because the task defines an RSM job, the user can choose to either run the task update locally or submit the calculations via RSM for remote job execution. Once the job has completed, Workbench merges the job back into the active session and retrieves results. The custom task defined in the extension then updates the custom property values to the externally-computed square value.
This example also demonstrates progress and project reporting functionality. The following figure shows the Data Squares task group in the Project Schematic.
The XML extension definition file DataSquares.xml performs the following actions:
References the IronPython script datasquares_complete.py.
Defines a single task in the <tasks>
block. Within this task:
Defines the callback
<onreport>, which is
called when the user generates a project report. This
allows the task to access the report object and add its
own task-specific reporting content.
Defines two property groups with the
<propertygroup> blocks.
Within the two property groups,
<property> tags define
the properties Input and
Output.
Defines the inputs and outputs in the
<inputs> and
<outputs> blocks. Note
that an empty input is defined here, although this is
not required.
Specifies via the
<rsmJob> block that the
task can be sent via RSM as a job for remote execution.
To specify RSM support, you add the
<rsmJob> block to the
task in the existing XML extension definition file. In
the RSM job specification:
Attributes specify the name and indicate the files to manage upon successful completion or cancellation of the job.
The <platform>
tags specify supported platforms.
The <argument>
tags specify the external application's command
line parameters, including input and output file
paths.
When using referenced file paths, the same
ID can be used across
categories but not within categories. An input and
an output can both have an
ID of 1, but two inputs
cannot have an ID of 1.
During the execution, all input and output file
names are transformed into fully qualified file
paths.
The <program>
block informs the extension about the task's
executable, supported platforms, and corresponding
command line arguments. Environment variables can
be used for the executable path and previously
defined arguments can be referenced by ID.
The callbacks invoke methods defined in the IronPython script to create the job, check job status, provide the capability to cancel the job, and access output files and results.
Defines a single task group in the
<taskgroups> block that includes
the task DataSquares
The file DataSquares.xml contains the following code:
<extension version="1" name="DataSquares">
<guid shortid="DataSquares">69d0095b-e138-4841-a13a-de12238c83f2</guid>
<script src="datasquares_complete.py" />
<interface context="Project">
<images>images</images>
</interface>
<workflow name="MyWorkflow" context="Project" version="1">
<tasks>
<task name="DataSquares" caption="Data Squares" icon="dsquares_component" version="1">
<callbacks>
<onupdate>update</onupdate>
<onstatus>status</onstatus>
<onreport>report</onreport>
<onreset>reset</onreset>
</callbacks>
<propertygroup name="Inputs">
<property name="Input" caption="Input" control="double" default="0.0" readonly="False"
needupdate="true" visible="True" persistent="True" isparameter="True" />
</propertygroup>
<propertygroup name="Outputs">
<property name="Output" caption="Output" control="double" default="0.0" readonly="True"
visible="True" persistent="True" isparameter="True" />
</propertygroup>
<inputs>
<input/>
</inputs>
<outputs/>
<rsmjob name="squares" deletefiles="True" version="1">
<inputfile id="1" name="input1.txt"/>
<outputfile id="1" name="output1.txt"/>
<program>
<platform name="Win64" path="%AWP_ROOT171%\Addins\ACT\extensions\DataSquares\
ExampleAddinExternalSolver.exe" />
<platform name="Linux64" path="%AWP_ROOT171%/Addins/ACT/extensions/DataSquares
/ExampleAddinExternalSolver.exe" />
<argument name="" value="inputFile:1" separator=""/>
<argument name="" value="outputFile:1" separator=""/>
</program>
<callbacks>
<oncreatejobinput>createJobInput</oncreatejobinput>
<onjobstatus>getJobStatus</onjobstatus>
<onjobcancellation>cancelJob</onjobcancellation>
<onjobreconnect>reconnectJob</onjobreconnect>
</callbacks>
</rsmjob>
</task>
</tasks>
<taskgroups>
<taskgroup name="DataSquares" caption="Data Squares" icon="dsquares" category="ACT Custom
Workflows" abbreviation="DSQRS" version="1">
<includeTask name="DataSquares" caption="Data Squares"/>
</taskgroup>
</taskgroups>
</workflow>
</extension>The following callbacks reference methods in the IronPython script. The first three callbacks invoke standard task actions. The subsequent callbacks invoke actions related to the RSM job specification.
<onupdate>Invokes the method update. Called when the
user updates the task.
<onstatus>Invokes the method status. Called when the
product (such as Workbench) asks the task for its current
state.
<onreport>Invokes the method report. Called when the
user generates a project report. This allows the extension to access
the report object and add their own task-specific reporting
content.
<oncreatejobinput>Invokes the method createJobInput. Called
when the RSM job requires the generation of all specified input
files. Must prepare and generate the input files specified for the
RSM job.
As a method argument, ACT passes in the fully qualified input file paths. For this example, only one input file is generated. It contains the input value for the squares solver. ACT retrieves the first entry from the input file list, opens the file, writes the input value line, and closes the file. ACT requires no further action.
<onjobstatus>Invokes the method getJobStatus. Must tell
Workbench if the job has finished. Polled by Workbench several times
during the RSM job execution to determine if the update execution
has completed. ACT supplies the fully qualified output file list as
a method argument.
For the example, True is returned when the
presence of the solver's sole output file is detected. Otherwise,
False is returned.
<onjobcancellation>Invokes the method cancelJob. Called when
the user stops the remote update before the job completes. Must
conduct any clean-up actions required due to a user-initiated
stoppage. ACT supplies the fully qualified lists of both input and
output files as method arguments.
For this example, no other action is performed. Only file cleanup
is required. Setting the method DeleteFiles
to True automatically handles the file
cleanup.
<onjobreconnect>Invokes the method reconnectJob. Called
when the job status reports a completed job. Must retrieve remotely
solved information from output files and update the task's data,
rendering it up-to-date.
For this example, the output file generated by the solver is read and the output property that is defined on the task is updated.
The next topic provides additional information about these methods.
The IronPython script dataquares_complete.py defines
methods that are invoked by callbacks in the XML extension definition file. The
methods update, status, and
report are standard methods defined for the task. The
methods createJobInput,
getJobStatus, cancelJob, and
reconnectJob are related to the RSM job
specification.
import clr
clr.AddReference("Ans.Core")
def update(task):
container = task.InternalObject
context = ExtAPI.DataModel.Context
activeDir = container.GetActiveDirectory()
extensionDir = ExtAPI.ExtensionManager.CurrentExtension.InstallDir
exeName = "ExampleAddinExternalSolver.exe"
solverPath = System.IO.Path.Combine(extensionDir, exeName)
monitor = context.ProgressMonitor
monitor.BeginTask("Data Sqaures Solver", 3, None)
monitor.TaskDetails = "Preparing solver input..."
System.Threading.Thread.Sleep(2000)
monitor.UpdateTask(1, None)
#get param values
inputValue = task.Properties["Inputs"].Properties["Input"].Value
#prep i/o file paths
inputFileName = "input.txt"
outputFileName = "output.txt"
dpInputFile = System.IO.Path.Combine(activeDir, inputFileName)
dpOutputFile = System.IO.Path.Combine(activeDir, outputFileName)
#write input file
f = open(dpInputFile, "w")
f.write('input='+inputValue.ToString(System.Globalization.NumberFormatInfo.InvariantInfo))
f.close()
monitor.UpdateTask(1, None)
monitor.TaskDetails = "Executing Solver..."
System.Threading.Thread.Sleep(2000)
#run exe
runInMono = Ansys.Utilities.ApplicationConfiguration.DefaultConfiguration.IsRuntimeMono
monoPath = "mono"
monoArgs = System.String.Format("{0} \"{1}\" \"{2}\"", solverPath, dpInputFile, dpOutputFile)
info = None
if runInMono:
info = System.Diagnostics.ProcessStartInfo(monoPath, monoArgs)
else:
info = System.Diagnostics.ProcessStartInfo(solverPath, System.String.Format("\"{0}\" \"{1}\"",
dpInputFile, dpOutputFile))
info.CreateNoWindow = True
info.WindowStyle = System.Diagnostics.ProcessWindowStyle.Minimized
p = System.Diagnostics.Process.Start(info)
p.WaitForExit()
monitor.UpdateTask(1, None)
monitor.TaskDetails = "Retrieving results from solver..."
System.Threading.Thread.Sleep(2000)
#read output file
outputValue = None
f = open(dpOutputFile, "r")
currLine = f.readline()
while currLine != "":
valuePair = currLine.split('=')
outputValue = System.Double.Parse(valuePair[1], System.Globalization.NumberFormatInfo.InvariantInfo)
currLine = f.readline()
f.close()
monitor.UpdateTask(1, None)
#set output value
if outputValue == None:
raise Exception("Error in update - no output value detected!")
else:
task.Properties["Outputs"].Properties["Output"].Value = outputValue
monitor.TaskDetails = "Solve completed..."
System.Threading.Thread.Sleep(2000)
monitor.EndTask(None)
def createJobInput(task, inputFilePaths):
ExtAPI.Log.WriteMessage('creating job input')
inputFilePath = inputFilePaths[0]
#get param values
inputValue = task.Properties["Inputs"].Properties["Input"].Value
#write input file
ExtAPI.Log.WriteMessage("Writing input value ("+str(inputValue)+") to file (" + inputFilePath + ")")
f = open(inputFilePath, "w")
f.write('input='+inputValue.ToString(System.Globalization.NumberFormatInfo.InvariantInfo))
f.close()
def reconnectJob(task, outputFilePaths):
ExtAPI.Log.WriteMessage('reconnecting job')
outputValue = None
outputFilePath = outputFilePaths[0] #I know we only have one specified based on our definition...so work
off of the first entry
f = open(outputFilePath, "r")
currLine = f.readline()
while currLine != "":
valuePair = currLine.split('=')
outputValue = System.Double.Parse(valuePair[1], System.Globalization.NumberFormatInfo.InvariantInfo)
currLine = f.readline()
f.close()
#set output value
ExtAPI.Log.WriteMessage("Retrieved value (" + str(outputValue) + ") from file (" + outputFilePath + ")")
if outputValue == None:
raise Exception("Error in update - no output value detected!")
else:
task.Properties["Outputs"].Properties["Output"].Value = outputValue
def getJobStatus(task, outputFiles):
ExtAPI.Log.WriteMessage('checking job status')
outputFilePath = outputFiles[0]
finished = System.IO.File.Exists(outputFilePath)
return finished
def cancelJob(task, inputFiles, outputFiles):
#nothing to do...just print a message for now.
ExtAPI.Log.WriteMessage('performing cancellation clean up')
import clr
clr.AddReference("Ans.ProjectSchematic")
clr.AddReference("ReportUtility.Interop")
import Ansys.ReportUtility.Interop
import Ansys.ProjectSchematic
def status(task):
status = Ansys.ProjectSchematic.Queries.ComponentState(Ansys.ProjectSchematic.State.Unfulfilled,
"This is unfulfilled!")
return None
def report(task, report):
root = report.GetRootSection()
section = Ansys.ReportUtility.Interop.ReportSection("My Custom ACT Task Report Content")
text = Ansys.ReportUtility.Interop.ReportText("", "Sample text from the data squares component")
section.AddChild(text)
root.AddChild(section)
def reset(task):
task.Properties["Inputs"].Properties["Input"].Value = 0
task.Properties["Outputs"].Properties["Output"].Value = 0Once you've defined an extension with an RSM job specification, you can submit your task as an RSM job for remote execution:
Install and load the extension to Workbench as usual.
Add a Data Squares task group to the Project Schematic.
Solution Process properties become available for the task group.
To specify that your task is to be executed remotely, set Update Option to .
Additional Solution Process properties become available.
Set your Solution Process properties. Then, save and update your project.
The task submits its process to RSM as a new job. Once RSM accepts the job, the task transitions to the pending state.
To view the status of your RSM job while it is being updated, open RSM.
Note: To run your jobs locally in the background, set Update Option to . Updates are then treated in a similar manner to true remote updates. Workbench prepares the update and invokes the same callbacks as in the example, but the update proceeds as a separate local update instead of engaging RSM.