Implementing a DesignXplorer Extension

A DesignXplorer extension has three main parts:

This section describes each of these pieces and includes references to several examples of functional DesignXplorer extensions.

Implementation Requirements

The implementation of a DesignXplorer extension requires:

  • ANSYS Workbench installation

  • ANSYS Customization Suite license

  • IronPython, which is provided as part of ANSYS Workbench in the directory <installdir>\commonfiles\IronPython

  • Microsoft Visual Studio 2010 SP1 for C# implementation

  • Microsoft Visual Studio 2010 SP1 or equivalent for C/C++ implementation

DesignXplorer Extension Definition and Configuration

As with any other type of extension, a DesignXplorer extension is defined and configured by an XML extension definition file that identifies the extension (version, name, author, description) and provides the following main entry points:

  • Filename of the main IronPython script (as specified by the <script> block)

  • Name of the function to invoke when initializing the extension (as specified by the callback <oninit>)

In a DesignXplorer extension, the callback <oninit> is the correct place to load the DLL containing the external sampling. Another callback named <onterminate> is invoked when the extension is unloaded and is the correct place to perform cleanup operations and unload the DLL.

A DesignXplorer extension specifically defines external sampling or optimization methods that DesignXplorer can use. The definitions are encapsulated in <simdata> blocks, where the attribute context is set to DesignXplorer.

The following figure shows the main blocks that you use to declare and define DOEs.

 

The DOE defined is called FullFactorial. The two attributes framed in red are examples of capabilities being defined for this DOE. Here you can see that for FullFactorial:

  • The attribute LogFile is set to true so that the sampling is capable of using the DesignXplorer API to generate a log file in the Workbench project.

  • The attribute CustomTable is set to false so that the DOE is not capable of handling the custom table available in DesignXplorer.

  • All other capabilities are configured per the default values. For more information, see DesignXplorer Extension Capabilities.

The callbacks to hook up with DesignXplorer are framed in blue. The callback <oncreate>, which is invoked to obtain an ISamplingMethod instance, is mandatory. All other callbacks are optional.

Finally, all of the properties declared for the DOE are framed in orange. These properties allow the user to control specific settings of the algorithm, access relevant output information (such as number of levels or status), or whatever else the DOE needs to expose as a result of the sampling run.

The next figure shows the main blocks used to declare and define the optimizers.

 

The extension is named MyOptimizer. It defines two different external optimizers. The declaration for each optimizer is marked with a green bracket. DesignXplorer manages each of these optimizers as an independent optimization method.

The first optimizer defined is called MyOptimizer. The two attributes framed in red are examples of capabilities being defined for this optimizer. Here you can see that for MyOptimizer:

  • The attribute SeekObjective is set to false, so the optimizer does not have the capability to handle the Seek Target objective available in DesignXplorer.

  • The attribute LogFile is set to true, so the optimizer has the capability to use the DesignXplorer API to generate a log file in the Workbench project.

  • All other capabilities are configured per the default values. For more information, see Optimization Example.

The callbacks to hook up with DesignXplorer are framed in blue. The callback OnCreate, which is invoked to obtain an IOptimizationMethod instance, is mandatory. All other callbacks are optional.

Finally, all of the properties declared for the optimizer are framed in orange. These properties allow the user to control specific settings of the algorithm, access relevant output information (such as the number of iterations, final convergence metrics, or status), or whatever else the optimizer needs to expose as a result of the optimization run.

DesignXplorer Extension Capabilities

A DesignXplorer extension is designed to solve a specific range of problems, and its implementation is characterized by complementary features and limitations. To allow DesignXplorer to determine when a given sampling or optimization method is applicable, depending on the current DOE or optimizer definition, it is necessary to declare the main capabilities of each external method. There are also optional capabilities that DesignXplorer uses to adjust the user interface according to what complementary features are supported by the external method.

For external DOEs, the capabilities are specified in the XML extension definition file as attributes of the <sampling> block. For external optimizers, the capabilities are specified in the XML extension definition file as attributes of the <optimizer> block.

Main Capabilities

The main capabilities are used to determine if the external sampling or optimization method can be applied to the problem as it is currently defined. If the external method has the required capabilities, it is available as a menu option in the DesignXplorer Properties view (applicable external samplings are available in the Design of Experiments Type menu, and applicable optimizers are available in the Method Name menu). If an external method is not applicable, it is not listed as a menu option. Each modification to the DOE or optimization study (such as modifying an existing input parameter or enabling or disabling an input parameter) triggers an evaluation of the relevant capabilities to reassess whether the external method is applicable and is to be made available to the user.

DOE Example

In the definition of the external DOE, the external sampling FullFactorial has MaximumNumberOfInputParameters set to 10. As a consequence, as soon as the user defines more than 10 input parameters, FullFactorial is removed from the list of available sampling methods. If the user then changes the DOE so that the number of input parameters is less than or equal to 10, FullFactorial is immediately restored as an available option.

If the user selects FullFactorial first and then defines more than 10 input parameters afterward, the sampling method is retained. Given the incompatibility of the sampling method and the number of input parameters, however, the state of the DOE changes to Edit Required. A Quick Help message is provided to explain why the sampling cannot be launched as currently configured.

Optimization Example

In the definition of the external optimizer, MyFirstOptimizer does not have the SeekObjective capability. As a consequence, as soon as the user defines a Seek Target objective, MyFirstOptimizer is removed from the list of available optimization methods. If the user then changes the optimization study so that the Seek Target objective is no longer defined, MyFirstOptimizer is immediately restored as an available option.

If the user selects MyFirstOptimizer first and then defines the unsupported Seek Target objective afterward, the optimization method is retained. Given the incompatibility of the optimization method and the objective, however, the state of the optimization changes to Edit Required. A Quick Help message is provided to explain why the optimization cannot be launched as currently configured.

The following table lists the main capabilities controlling the availability of external methods.

DOEOptimizer

MaximumNumberOfInputParameters

MaximumNumberOfInputParameters

MaximumNumberOfDoubleParameters

MaximumNumberOfDoubleParameters

MaximumNumberOfDoubleListParameters

MaximumNumberOfDoubleListParameters

MaximumNumberOfIntegerListParameters

MaximumNumberOfIntegerListParameters

ParameterRelationship

ObjectiveOnInputParameter

ConstraintOnInputParameter

MinimizeObjective

MaximizeObjective

SeekObjective

LessThanConstraint

GreaterThanConstraint

EqualToConstraint

InsideBoundsConstraint

MinimumNumberOfObjectives

MaximumNumberOfObjectives

MinimumNumberOfConstraints

MaximumNumberOfConstraints

BasedOnResponseSurfaceOnly

BasedOnDirectOptimizationOnly

For a comprehensive list of capabilities, see the "Sampling" and "Optimizer" sections in the ANSYS ACT API Reference Guide and ANSYS ACT XML Reference Guide.

Optional Capabilities

The optional capabilities are used to enable or disable specific options or features of DesignXplorer according to the level of support provided by the selected external method. After the main capabilities have established that a method is applicable to a given DOE or optimization study, the optional capabilities determine which features to expose for that method in the DesignXplorer user interface.

For example, the LogFile capability is declared for the sampling defined for the external DOE, FullFactorial, and also for the external optimizer defined in MyFirstOptimizer. As a result, the corresponding features for managing and exposing the log file are enabled in DesignXplorer and exposed in the user interface. If this capability was not declared or was set to false, DesignXplorer would adjust its user interface to hide the access to the log file because it is not supported by this external method.

As additional examples:

  • If the selected sampling does not support the Custom Table capability, Custom Table is not available in the user interface.

  • If the selected optimizer does not support the Maximize objective type, the objective types available in the user interface are limited to Minimize and Seek Target.

  • If the optimizer does not support importance levels on objectives, the property Objective Importance is not available in the Property view of the optimization criterion.

For a comprehensive list of capabilities, see the "Sampling" and "Optimizer" sections in the ANSYS ACT API Reference Guide and ANSYS ACT XML Reference Guide.


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