ANSYS ACT Customization Guide for

DesignXplorer

ANSYS, Inc. Release 2020 R1

Southpointe January 2020
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

© 2020 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
Introduction ............................................................................................................................................... 1
DesignXplorer Systems and Components ................................................................................................ 1
DesignXplorer External Method Integration ............................................................................................ 2
DesignXplorer Process ............................................................................................................................ 3
DesignXplorer Feature Creation ................................................................................................................ 7
ACT-Based Properties for External Methods ............................................................................................ 7
Properties in DesignXplorer .............................................................................................................. 8
Additional Attributes for DesignXplorer Extensions ........................................................................... 9
Advanced Usage Examples ............................................................................................................. 10
Managing Dependencies Between Properties ........................................................................... 10
Controlling Property Visibility with a Callback ............................................................................ 10
Modifying an Attribute with a Callback ...................................................................................... 11
DesignXplorer Extension Implementation ............................................................................................. 12
Implementation Requirements ....................................................................................................... 13
DesignXplorer Extension Definition and Configuration .................................................................... 13
DesignXplorer Extension Capabilities .................................................................................................... 16
Main Capabilities ............................................................................................................................ 16
Optional Capabilities ...................................................................................................................... 18
Notes on Method Class Implementation ................................................................................................ 18
Notes on Monitoring ...................................................................................................................... 19
Notes on Results ............................................................................................................................. 19
DesignExplorer APIs ................................................................................................................................. 21
DOE APIs .............................................................................................................................................. 21
DOE Architecture ............................................................................................................................ 21
Sampling Process ........................................................................................................................... 22
Optimization APIs ................................................................................................................................. 22
Optimization Architecture .............................................................................................................. 23
Optimization Process ...................................................................................................................... 23

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. iii
 Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
iv of ANSYS, Inc. and its subsidiaries and affiliates.
Introduction
This guide assumes that you are familiar with the general ACT usage information in the ACT Developer's
Guide. It supplies only information specific to using ACT with DesignXplorer.

This first section summarizes DesignXplorer concepts with which you must be familiar:
DesignXplorer Systems and Components
DesignXplorer External Method Integration
DesignXplorer Process

Subsequent content is organized into primary sections as follows:

• DesignXplorer Feature Creation (p. 7): Provides examples of integrating external sampling and optim-
ization methods.

• DesignExplorer APIs (p. 21): Describes the ACT APIs that provide for customizing the interface and
functionality of DesignXplorer.

Note:

• Because DesignXplorer is part of Workbench, you can create project wizards and mixed wizards
that can engage DesignXplorer. For the wizard step, you simply need to set the attribute <con-
text> to Project. Because DesignXplorer does not have a stand-alone application interface,
you cannot create target product wizards for DesignXplorer.

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

DesignXplorer Systems and Components

DesignXplorer exposes several types of systems in Workbench, with each system corresponding to a
type of parametric analysis. In the Workbench Toolbox, DesignXplorer systems are listed under Design
Exploration. Each of these systems consists of components, which are referred to as cells.

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

Design of Experiments Cell

Three design exploration systems include a Design of Experiments cell: Response Surface, Response
Surface Optimization, and ROM Builder. This cell provides a selection of built-in sampling methods
(DOE types). Each sampling method comes with its own specific standard and advanced properties,
capabilities, and limitations.

Optimization Cell
Two design exploration systems include a Design of Experiments cell: Direct Optimization and Re-
sponse Surface Optimization. This cell provides a selection of built-in optimization methods. Each
optimization method comes with its own specific standard and advanced properties, capabilities, and
limitations.

Direct Optimization System

• This system has only an Optimization cell.

• Each point requested by the optimizer is calculated by updating a design point (real solve).

• With this approach:

– The optimizer manipulates accurate output parameter values that are directly returned by the solver.

– The number of input parameters is not limited. However, the cost is proportional to the number of
points.

Response Surface Optimization System

• This system has three cells: Design of Experiments, Response Surface, and Optimization.

• Each point requested by the optimizer is calculated by evaluating the response surface.

• With this approach:

– The optimizer manipulates approximated output parameter values.

– The number of input parameters is limited by the ability to generate the response surface. However, the
cost is extremely low because the resources needed to evaluate the response surface are negligible. The
optimization is performed as a postprocessing operation based on the response surface, so several altern-
ative optimization studies can be performed very quickly on the same surface.

DesignXplorer External Method Integration

DesignXplorer offers design exploration and optimization features. Using extensions, you can integrate
external sampling methods (DOE types) and optimization methods. DesignXplorer then exposes these
additional methods, along with specific properties for controlling their behavior.

Through its API, DesignXplorer provides the services required to calculate points, report progress, and
return results. Consequently, the user experience is the same in DesignXplorer for both built-in and
external sampling and optimization methods.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
2 of ANSYS, Inc. and its subsidiaries and affiliates.
 DesignXplorer Process

An extension for integrating external sampling and optimization methods includes specific elements
for the DesignXplorer context. You generally code a callback class in C#, C/C++ or Fortran for the instan-
tiation of the external method. The callback class must implement the interface for the sampling
method (ISamplingMethod) or optimization method (IOptimizationMethod) for DesignXplorer
to recognize it as valid.

DesignXplorer takes advantage of the Workbench platform to allow parametric studies in a generic way
for any simulation project. Regardless of the number of solvers and physics or the complexity of the
workflow involved to execute the simulation, DesignXplorer sees the same simplified representation of
the project and interacts with it only in terms of parameters, design points, and the associated services.

This generic architecture makes it possible to implement a variety of algorithms without needing to
worry about the communication with solvers. Because DesignXplorer hosts the external methods, they
also can take advantage of the Workbench platform architecture to work with any kind of simulation
project defined in Workbench, with no additional implementation effort.

DesignXplorer Process
The external functionality defined by the extension is responsible for carrying out relevant analysis tasks
defined in DesignXplorer. The external sampling method is responsible for generating the DOE, and
the external optimization method is responsible for solving the optimization study. The external func-
tionality does not have to support all the features available in DesignXplorer. However, because the
external method is hosted in the DesignXplorer environment, it is subject to the environment's limitations.
Consequently, some external features might not be available in DesignXplorer.

DOE and optimization studies are defined as follows:

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 3
Introduction

DOE Study Optimization Study

Variables Variables
DOE domain Optimization domain
Parameter relationships
Objectives
Constraints

Variables are the parameters in the Workbench project. Just as there are input and output parameters
in the project, there are input and output variables for the sampling or optimization method. Because
input parameters can be disabled, the number of input variables transferred to the external functionality
is smaller than or equal to the number of input parameters defined in the Workbench project.

The domain is the multidimensional space that the sampling method can explore to generate the DOE
or the optimization method can explore to solve the optimization problem. The domain is defined
either by the input variables and their range of variation or by a list of possible values. There are different
types of input variables:

• Double Variable:

– Continuous variable defined by a range of variation, from its lower bound to its upper bound, where the
bounds are real values

– Exposed as a continuous input parameter

• Double List Variable:

– Defined by a list of sorted real values

– Exposed as a continuous input parameter with manufacturable values

• Integer List Variable:

– Defined by a list of integer values

– Exposed as a discrete input parameter

Parameter relationships for an optimization define relationships between input variables, such as P1+2*P2
<= 12.5[mm]. They allow the definition of the optimization domain to be restricted.

Objectives for an optimization are defined on variables, such as Minimize P3. The following objective
types are supported:

• Minimize a variable

• Maximize a variable

• Seek Target for a variable, where the target is a user-specified constant value

Constraints for an optimization are defined on variables as well, such as P3 <= 80. Both an objective
and a constraint can be defined for the same variable. The following constraint types are supported:

• Less Than, which defines the lower bound (constant value)

• Greater Than, which defines the upper bound (constant value)

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
4 of ANSYS, Inc. and its subsidiaries and affiliates.
 DesignXplorer Process

• Equal To, which defines the target value (constant value)

• Inside Bounds, which defines the targeted interval (constant values)

The next section supplies additional information about creating DesignXplorer features by implementing
external sampling and optimization methods.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 5
 Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
6 of ANSYS, Inc. and its subsidiaries and affiliates.
DesignXplorer Feature Creation
In addition to supporting the common feature creation capabilities described in the ANSYS ACT Developer's
Guide, DesignXplorer supports using extensions to integrate external sampling and optimization
methods:
ACT-Based Properties for External Methods
DesignXplorer Extension Implementation
DesignXplorer Extension Capabilities
Notes on Method Class Implementation

Note:

The package ACT Templates for DesignXplorer provides five templates. Two of these
templates show how to generate design point samples. The other three templates show how
to optimize the design space. These examples use the IronPython, C#, or C/C++ methods so
that you can see how to accomplish an objective using different programming languages.
For more information, see ACT Templates for DesignXplorer in the ANSYS ACT Developer's
Guide. For download information, see Extension and Template Examples.

ACT-Based Properties for External Methods

An external sampling or optimization method can expose ACT-based properties so that algorithm options
and view outputs can be controlled.

For instance:

• A DOE can expose the editable property Number of Levels so that a limit can be defined. The sampling is
responsible for handling this property as needed. The DOE can also expose the read-only property Actual
Number of Points to indicate the number of points generated once the sampling is completed.

• An optimizer can expose the editable property Maximum Number of Iterations so that a limit can be
defined. The optimizer is responsible for handling this property as needed. The optimizer can also expose
the read-only property Actual Number of Iterations to indicate the number of iterations actually performed
once the optimization is completed.

ACT provides support for the general definition of properties with attributes and callbacks. Each property
to expose in DesignXplorer must be declared and defined in the extension's XML file using a child element
<property> under the parent element <sampling> or <optimizer>.
<property name="[property internal name (string)]"
caption="[property display name (string)]"
readonly="[true | false(default)]"
default="[default value]"
control="[text(default) | select | float | integer | ...]"
visible="[true(default) | false]"
visibleon="[values(separator '|')]"
...

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 7
DesignXplorer Feature Creation

<attributes>mldr</attributes>
<callbacks>
</property>

Optionally, properties can be placed together in groups. Each group must be declared and defined in
the XML file as a child element <propertygroup> under the parent element <sampling> or <op-
timizer>.

For a description of common attributes and callbacks, see "property" in the "XML Tags" section of the
ACT API Reference Guide for DesignXplorer. For more information on property groups, see "property-
group" in the ACT XML Reference Guide.

Properties in DesignXplorer
You can select an external method in DesignXplorer for Design of Experiments Type for a DOE or
Method Name for an optimization. When an external method is selected, its properties are shown
in the Properties pane.

The following figure shows the Properties pane when an external sampling named Full Factorial is
selected for Design of Experiments Type.

This next figure shows the Properties pane when an external optimizer named Python Optimizer
is selected for Method Name.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
8 of ANSYS, Inc. and its subsidiaries and affiliates.
 ACT-Based Properties for External Methods

By default, properties for the external method are shown under the General category. If a proper-
tygroup is specified, the corresponding category is created in the property view. The properties
under the General and respective Status categories are specific to the external method and are
defined in the XML file.

If the external method supports the LogFile capability, the property LogFile is automatically
defined under the Status category in the Properties pane. Once the sampling is generated or the
optimization has been run, the log file can be viewed by clicking the available link.

Additional Attributes for DesignXplorer Extensions

In the context of sampling and optimization extensions, DesignXplorer also recognizes the additional
attributes min, max, and advanced for each property. The attributes min and max are used to
specify a minimum value, maximum value, or both values for a double or integer property.

In the following sampling example, the minimum value is 1 and the maximum value is 100.
<property name="NumberOfLevels" caption="Number of Levels" control="integer" default="3">
<attributes min="1" max="100"/>
</property>

In the following optimization example, the minimum value is 2 and the maximum value is 200.
<property name="MyNumberOfSamples" caption="My Number of Samples" control="integer" default="50">
<attributes min="2" max="200"/>
</property>

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 9
DesignXplorer Feature Creation

The attribute advanced is used to classify the property as an advanced option. Advanced options
are visible only if activated. To activate them, in Options → Manage Design Exploration, select the
Show Advanced Options check box.

The following example is applicable to either type of DesignXplorer extension.

<property name="MyRandomNumber" caption="My Random Number provider" control="select"
default="Python">
<attributes options="Python,CLibrary" advanced="true"/>
</property>

Advanced Usage Examples

The following topics describe using advanced properties in DesignXplorer extensions:
Managing Dependencies Between Properties
Controlling Property Visibility with a Callback
Modifying an Attribute with a Callback

Managing Dependencies Between Properties

The following example demonstrates how to manage the dependency between properties:

• Prop1 is visible when the value Group3 is equal to Option 1

• Prop2 is visible when the value Group3 is equal to Option 1 or Option 2

• Prop3 is visible when the value Group3 is equal to Option 3

<propertygroup name="Group3" caption="Group Select" display="property" control="select"
default="Option 1">
<attributes options="Option 1,Option 2,Option 3" />
<property name="Prop1" caption="Prop For Option 1" visibleon="Option 1" control="text" />
<property name="Prop2" caption="Prop For Option 1 and Option 2" visibleon="Option 1|Option 2"
control="text" />
<!-- Prop3 is applicable and visible only when Group3 == "Option 3" -->
<property name="Prop3" caption="Prop For Option 3" visibleon="Option 3" control="text" />
</propertygroup>

Controlling Property Visibility with a Callback

Property attributes, such as visibility, can be modified dynamically by using a callback.

DOE Example
The following example shows how to control the visibility of the property PropForSingleInput
with a callback coded in IronPython:
<property name="PropForSingleInput" caption="My Property for single input parameter"
control="text">
<callbacks>
<isvisible>isVisibleForSingInput</isvisible>
</callbacks>
</property>

Where the function isVisibleForSingInput is defined by the following IronPython code:

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
10 of ANSYS, Inc. and its subsidiaries and affiliates.
 ACT-Based Properties for External Methods

def isVisibleForSinglnput(entity,property):
if entity.NumberOfInputParametersDefined == 1:
return True
return False

The function isVisibleForSinglnputfunction takes two arguments:

• The first argument-named entity is of type DXUserSampling.

• The second argument-named property is of type SimProperty.

This function returns True when only one input parameter is defined.

Optimization Example
The following example shows how to control the visibility of the property PropForSingleOb-
jective with a callback coded in IronPython:
<property name="PropForSingleObjective" caption="My Property for single-objective optimization"
control="text">
<callbacks>
<isvisible>isVisibleForSOO</isvisible>
</callbacks>
</property>

Where the function isVisibleForSOO is defined by the following IronPython code:

def isVisibleForSOO(entity,property):
if entity.NumberOfObjectivesDefined == 1:
return True
return False

The function isVisibleForSOO takes two arguments:

• The first argument-named entity is of type DXUserOptimizer.

• The second argument-named property is of type SimProperty.

This function returns True when only one objective is defined.

Modifying an Attribute with a Callback

The following examples show how you can modify the values property attributes when input
parameters are edited by the user.

DOE Example
This example shows how you can modify the values of the attribute max for the property Number-
OfLevels when input parameters are edited by the user.

Given the partial sampling definition:

<sampling …>
<callbacks>
<InputParametersEdited>InputParametersEdited</InputParametersEdited>
</callbacks>
<property name="NumberOfLevels" caption="Number of Levels" control="integer" default="3"/>
<attributes min="1">

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 11
DesignXplorer Feature Creation

</property>
</sampling>

The function InputParametersEdited is defined by the following IronPython code:

def InputParametersEdited(entity):
entity.Properties["NumberOfLevels"].Attributes["max"]=3*entity.NumberOfInputParametersDefined

The function InputParametersEdited is called when a user edits the input parameters. This
function calculates the new minimum allowed value for the property NumberOfLevels from the
current number of input parameters and then sets this value to the attribute max.

Optimization Example
This example shows how you can modify the values of the attribute min for the property MyNum-
berOfSamples when input parameters are edited by the user.

Given the partial optimizer definition:

<optimizer …>
<callbacks>
<InputParametersEdited>InputParametersEdited</InputParametersEdited>
</callbacks>
<property name="MyNumberOfSamples" caption="My Number of Samples" control="integer" default="50">
<attributes min="2" max="1000"/>
</property>
</optimizer>

The function InputParametersEdited is defined by the following IronPython code:

def InputParametersEdited(entity):
entity.Properties["MyNumberOfSamples"].Attributes["min"]=10*entity.NumberOfInputParametersDefined

The function InputParametersEdited is called when input parameters are edited by the user.
It calculates the new minimum allowed value for the property MyNumberOfSamples from the
current number of input parameters and then sets this value to the attribute min.

DesignXplorer Extension Implementation

A DesignXplorer extension has three main pieces:

• XML extension definition file that declares, defines, and configures the extension

• One or more IronPython scripts that implement callbacks

• ISamplingMethod or IOptimizationMethod implementation, which is the adapter to your existing

implementation. This is typically achieved in C# or IronPython.

The following topics describe each of these pieces and include references to several examples of func-
tional DesignXplorer extensions:
Implementation Requirements
DesignXplorer Extension Definition and Configuration

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
12 of ANSYS, Inc. and its subsidiaries and affiliates.
 DesignXplorer Extension Implementation

You can compile a DesignXplorer extension into a binary version (WBEX file) to share external sampling
and optimization methods with others. When DesignXplorer extensions are installed and loaded,
DesignXplorer detects the external sampling and optimization methods and makes them available for
selection. When a external method is selected, DesignXplorer delegates to this method. When an ex-
ternal method is used, the Workbench session is journalled and can be replayed as usual.

Implementation Requirements
The implementation of a DesignXplorer extension requires:

• A Workbench installation

• An ACT license

• IronPython, which is provided as part of Workbench and located in the directory installdir\common-
files\IronPython

• Microsoft Visual Studio 2017 Update 15.0.19 for a C# or C++ implementation

DesignXplorer Extension Definition and Configuration

As with any other type of extension, a DesignXplorer extension is defined and configured by an XML
file that identifies the extension and provides the following main entry points:

• File name of the main IronPython script (as specified by the element <script>)

• 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 method. Another callback named <onterminate> is invoked when the ex-
tension is unloaded. It is the correct place to perform cleanup operations and unload the DLL.

A DesignXplorer extension specifically defines external sampling and optimization methods that
DesignXplorer can use. The element <simdata> encapsulates the method definitions. The attribute
context is set to DesignXplorer.

The following figure shows the main elements for declaring and defining an external sampling
method. The extension, named PythonSampling, is a supplied DesignXplorer template. For
download information, see Extension and Template Examples in the ANSYS ACT Developer's Guide.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 13
DesignXplorer Feature Creation

The element <simdata> defines a single external sampling method named FullFactorial. The
two attributes framed in red are examples of capabilities being defined for this DOE type. For Full-
Factorial, you can see that:

• The attribute LogFile is set to true so that the DOE type 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 type 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 Ex-
tension Capabilities (p. 16).

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 properties declared for the DOE type are framed in orange. These properties control spe-
cific settings of the algorithm, access relevant output information (such as number of levels or status),
and supply other information that the DOE type needs to expose as a result of the sampling run.

The next figure shows the main elements for declaring and defining an external optimizer. This exten-
sion, named MyOptimizer, is not supplied.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
14 of ANSYS, Inc. and its subsidiaries and affiliates.
 DesignXplorer Extension Implementation

The element <simdata> 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 is named MyFirstOptimizer. The two attributes framed in red are examples
of capabilities being defined for this optimizer. Here you can see that for MyFirstOptimizer:

• The attribute SeekObjective is set to false so that the optimizer is not capability of handling the
objective Seek Target in DesignXplorer.

• The attribute LogFile is set to true so that the optimizer is capable of using 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 Ex-
ample (p. 17).

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.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 15
DesignXplorer Feature Creation

Finally, all properties declared for the external optimization method are framed in orange. These
properties control specific settings of the algorithm, access relevant output information (such as the
number of iterations, final convergence metrics, and status), and provide 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 optimization
definition, it is necessary to declare the main capabilities of each external method. There are also op-
tional capabilities that DesignXplorer uses to adjust the interface according to what complementary
features are supported by the external method.

For external sampling methods, capabilities are specified in the XML file as attributes of the element
<sampling>. For external optimization methods, capabilities are specified in the XML file as attributes
of the element <optimizer>.

The following topics describe capabilities:

Main Capabilities
Optional Capabilities

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,
DesignXplorer makes it available as a choice in the Properties pane.

• Applicable external sampling methods are choices for Design of Experiments Type.

• Applicable optimization methods are available for Method Name.

If an external method is not applicable, it is not listed as a choice. 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 for selection.

DOE Example
In the definition of the external sample method FullFactorial, the attribute MaximumNumber-
OfInputParameters set to 10. As a consequence, as soon as more than 10 input parameters are
defined, FullFactorial is removed from the list for Design of Experiments Type. If the DOE is then
changed so that the number of input parameters is less than or equal to 10, FullFactorial is immedi-
ately restored as an available choice.

If Design of Experiments Type is set to FullFactorial and more than 10 input parameters are defined
afterward, the sampling method is retained. However, given the incompatibility of the sampling
method and the number of input parameters, the state of the DOE changes to Edit Required. A Quick
Help message is provided to explain why the sampling cannot be started as currently configured.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
16 of ANSYS, Inc. and its subsidiaries and affiliates.
 DesignXplorer Extension Capabilities

Optimization Example
In the definition of the external optimization method MyFirstOptimizer, the attribute SeekOb-
jective is set to false. As a consequence, as soon as a Seek Target objective is defined, My-
FirstOptimizer is removed from the list for Method Name. If the optimization study is changed so
that the Seek Target objective is no longer defined, MyFirstOptimizer is immediately restored as
an available choice.

If Method Name is set to MyFirstOptimizer and the unsupported Seek Target objective is defined
afterward, the optimization method is retained. However, given the incompatibility of the optimization
method and the objective, the state of the optimization changes to Edit Required. A Quick Help
message is provided to explain why the optimization cannot be started as currently configured.

Main Capabilities List

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

DOE Optimizer
MaximumNumberOfInputParameters MaximumNumberOfInputParameters
MaximumNumberOfDoubleParameters MaximumNumberOfDoubleParameters
MaximumNumberOfDoubleListParamet- MaximumNumberOfDoubleListParamet-
ers ers
MaximumNumberOfIntegerListPara- MaximumNumberOfIntegerListPara-
meters meters
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 ACT API
Reference Guide and ACT XML Reference Guide.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 17
DesignXplorer Feature Creation

Optional Capabilities
Optional capabilities are used to enable or disable specific DesignXplorer options or features 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 this method in DesignXplorer.

For example, the attribute LogFile is set to true for the external sampling method FullFactori-
al and for the external optimization method MyFirstOptimizer. As a result, the corresponding
features for managing and exposing the log file are enabled and exposed in DesignXplorer. If the
attribute LogFile was not declared or set to false, DesignXplorer would hide access to the log
file because it would not be supported by this external method.

As additional examples:

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

• 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 ACT API
Reference Guide and ACT XML Reference Guide.

Notes on Method Class Implementation

The main interface method classes are ISamplingMethod for an external sampling method and
IOptimizationMethod for an external optimization method. An implementation of the main interface
method class for an external method is mandatory for a DesignXplorer extension to be valid. This
method class is the core of the extension. It is the object that is delegated the responsibility to generate
the sampling or solve the optimization study.

• If you start a completely new implementation of the sampling or optimization algorithm, you might consider
writing a C# class that derives directly from the method class, as provided by the PublicAPIs assembly.

• If you start from existing code, either in C/C++ or FORTRAN code, you should consider implementing your
method class in IronPython as an adapter to your algorithm implementation, wrapping your existing classes
and routines.

Both approaches are illustrated by supplied templates. For more information, see ACT Templates for
DesignXplorer in the ANSYS ACT Developer's Guide. For full API reference documentation, see "API De-
scription" in the ACT API Reference Guide.

The following topics provide additional notes:

Notes on Monitoring
Notes on Results

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
18 of ANSYS, Inc. and its subsidiaries and affiliates.
 Notes on Method Class Implementation

Notes on Monitoring
Sampling Monitoring

In addition to progress and log messages, DesignXplorer provides user interface elements for monit-
oring the progress of a sampling.

Optimization Monitoring

In addition to progress and log messages, DesignXplorer provides user interface elements for monit-
oring the progress of an optimization. The API allows the external optimizer to optionally provide
DesignXplorer with progress data such as history and convergence values.

History values are values of the input and output variables that show how the optimizer explores the
parametric space. In DesignXplorer, history values are rendered graphically as a 2D chart per objective
and input parameter. The X axis represents points or iterations, and the Y axis represents the para-
meter values. For more information, see Using the History Chart in the DesignXplorer User's Guide.

In the extension's XML file, you can configure the X axis to represent points or iterations by setting
the attribute HistoryChartXAxisType for the optimizer element to either byPoint or byIter-
ation.

To provide history values during the execution of IOptimizationMethod.Run(), the optimization

method can call IOptimizationServices.PushHistoryPoint(IOptimizationPoint
point), where point contains a value for some or all enabled input and output variables.

Convergence values are independent from the variables. They are the values of one or more convergence
metrics, specific to your optimizer and showing its convergence during the process. In DesignXplorer,
convergence values are rendered graphically as a 2D chart with one or several curves. For more in-
formation, see Using the Convergence Criteria Chart in the DesignXplorer User's Guide.

To provide convergence values during the execution of IOptimizationMethod.Run(), the op-

timization method can call IOptimizationServices.PushConvergenceData (IConver-
genceData data), where data contains the values for one or several convergence criteria.

Notes on Results
Sampling Results

DOE postprocessing is similar for all DOE types. Once the DOE is generated, DesignXplorer extracts
all results provided by the sampling to generate postprocessing tables and charts:

Sample points from the property ISamplingMethod.Samples

Optimization Results

Optimization postprocessing is similar for all optimization methods. Once the optimization is solved,
DesignXplorer checks IOptimizationMethod.PostProcessingTypes and extracts all results
provided by the optimizer to generate postprocessing tables and charts:

• Candidate points from the property IOptimizationMethod.Candidates

• Sample points from the property IOptimizationMethod.Samples

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 19
DesignXplorer Feature Creation

• Pareto fronts from the property IOptimizationMethod.ParetoFrontIndex

In some cases, DesignXplorer builds missing results if one of these result types is not supported. For
example, if the optimization method provides the sample points without the candidate points,
DesignXplorer applies its own sorting logic to generate the candidate points based on objectives and
constraints definitions. If the optimizer provides the sample points without the Pareto fronts indices,
DesignXplorer builds missing data based on objectives and constraints definitions.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
20 of ANSYS, Inc. and its subsidiaries and affiliates.
DesignExplorer APIs
ACT provides APIs for customizing the interface and functionality of DesignXplorer. The following topics
describe how to use DesignXplorer APIs to customize DOE and optimization functionality:
DOE APIs
Optimization APIs

For comprehensive information on all ACT APIs and their properties, refer to the ACT API Reference Guide.

DOE APIs
The following topics describe how to use DesignXplorer APIs to customize DOE functionality:
DOE Architecture
Sampling Process

DOE Architecture
The object PSMtrxGenerator is responsible for the execution of the DOE. Regardless of whether
the sampling is built-in or external, this object executes the same process via the sampling API.

The following figure shows the DesignXplorer sampling architecture.

The main elements of the API are:

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 21
DesignExplorer APIs

• ISamplingMethod: Main interface between DesignXplorer and the external sampling, which is required
to implement it

• IServices: Interface for the external sampling to access DesignXplorer services, such as the calculation
of one or more points

• DXPoint: Class that describes and stores the point data, such as variable values and calculation state.

For more information, see the "API Description" section for DesignXplorer in the ACT API Reference
Guide.

Sampling Process
The PSMtrxGenerator object drives the sampling process as shown in the following sequence
diagram.

First, the sampling process retrieves an instance of the sampling through the callback declared in the
extension. It provides the object Services and transfers the complete sampling definition: all vari-
ables, parameters, and settings.

The object PSMtrxGenerator retrieves an instance of the sampling each time the sampling process
is started by invoking the callback OnCreate. The object PSMtrxGenerator releases the instance
on completion by invoking the callback OnRelease.

After a final check CanRun, the sampling's method Run is invoked. From this point in the sequence,
the external sampling triggers the calculation of points as needed and pushes progress messages
and log messages, depending on its capabilities.

Optimization APIs
The following topics describe how to use DesignXplorer APIs to customize optimization functionality:
Optimization Architecture
Optimization Process

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
22 of ANSYS, Inc. and its subsidiaries and affiliates.
 Optimization APIs

Optimization Architecture
The object OptimizationEngineMgr is responsible for the execution of the optimization. Regardless
of whether the optimizer is built-in or external, it executes the same process via the optimization API.

The following figure shows the DesignXplorer optimization architecture.

The main elements of the API are:

• IOptimizationMethod: Main interface between DesignXplorer and the external optimizer, which is
required to implement it

• IOptimizationServices: Interface for the external optimizer to access DesignXplorer services, such
as the calculation of one or more points

• DXOptimizationPoint: Class that describes and stores the points data, such as variable values and
calculation state.

For more information, see the "API Description" section in the ACT API Reference Guide.

Optimization Process
The object OptimizationEngineMgr drives the optimization process as shown in the following
sequence diagram.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 23
DesignExplorer APIs

First, the optimization process retrieves an instance of the optimizer through the callback declared
in the extension. It provides the object Services and transfers the complete optimization study
definition, which includes all variables, parameter relationships, objectives, constraints, and settings.

The object OptimizationEngineMgr retrieves an instance of the optimizer each time the optim-
ization process is started by invoking the callback OnCreate. The object OptimizationEngineMgr
releases the instance on completion by invoking the callback OnRelease.

After a final check CanRun, the optimizer's method Run is invoked. From this point in the sequence,
the external optimizer triggers the calculation of points as needed and pushes progress messages,
history points, convergence values, and log messages, depending on its capabilities.

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
24 of ANSYS, Inc. and its subsidiaries and affiliates.