Custom, Lightweight, External Application Integration with Custom Data and Remote Job Execution

The extension DataSquares demonstrates:

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.

 

XML Extension Definition File

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.

IronPython Script

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 = 0

Using RSM Job Submission Capabilities

Once you've defined an extension with an RSM job specification, you can submit your task as an RSM job for remote execution:

  1. Install and load the extension to Workbench as usual.

  2. Add a Data Squares task group to the Project Schematic.

    Solution Process properties become available for the task group.

     

  3. To specify that your task is to be executed remotely, set Update Option to Submit to Remote Solve Manager.

    Additional Solution Process properties become available.

     

  4. 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.

     

  5. 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 Run in Background. 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.



Release 18.2 - © ANSYS, Inc. All rights reserved.