Manual on how to use the Optimization Algorithm API.
The RCE Optimization Algorithm API enables the user to integrate their own optimization algorithms into RCE and use them in the common Optimizer Component. The API is based on Python, so the user's algorithm must be callable from phyton, e.g. through a system call.
The location where the API looks for integrated algorithms is in RCE's profile folder:
<profile>/integration/optimizer/.
Below this path, every subfolder must have a specific structure in order to be recognized as an optimizer integration. Each subfolder must contain two folders with the names
"gui_properties_configuration" and "source".
An example integration "example_algorithm" is available at the installation path of RCE in the subfolder
"examples/optimization_algorithm_api/optimizer". Copy it to your profile and you can use this algorithm in RCE.
Within the "gui_properties_configuration" folder, the GUI of the Optimizer Component must be configured for the integrated algorithms. At first, there has to be a file named "algorithms.json". In this file, RCE looks for the algorithms to be defined. The file is structured as follows:
{
"Name of algorithm":"name of json file for algorithm"
}
For example:
{
"Name of method1" : "method1",
"Name of method2" : "method2"
}
where "method1.json" and "method2.json" exist in the same directory.
The method files also have to be in a certain format which looks like this:
{
"methodName":"Name of method",
"optimizerPackage":"generic",
"specificSettings":{
"propertyName":{
"GuiName":"Name shown in optimizer GUI",
"dataType": ["Int" | "Real" | "String" | "Bool"],
"SWTWidget": ["Text" | "Combo" | "Check"],
"DefaultValue": "",
"Value":"",
"Validation":""
}
}
}
The "optimizerPackage" must always have the value "generic" and the "methodName" must have the same value as defined in the "algorithms.json". In the section "specificSettings", properties can be defined in order to make them configurable in the RCE GUI. You can choose between three different types of GUI widgets and four different data types. The properties will be displayed when you open the "Algorithm properties..." view in the RCE's Algorithm section of the Optimizer component. Three categories are available to organize the properties on different tabs: "commonSettings","specificSettings" and "responsesSettings".
Every property must have the following fields:
GuiName: The name that is displayed in the "Algorithm properties..." view and describes the property.
dataType: The data type of the current property. Valid values are:
Int: an integer number
Real: a float number
String: a text
SWTWidget: This value defines what kind of GUI element is used for the property. Valid values are:
Text: a text box where the user can enter any string
Combo: a dropdown menu with pre defined values. When using the Combo, you have to define the values to be shown, using:
Choices: A comma separated list of the values, e.g. "Option 1, Option 2"
Check: a checkbox to select an option
DefaultValue: The default value that is chosen if the user does not manually enter a value for the property. For Combos, this must be one of the "Choices".
Value: The value must always be an empty string ("").
Validation: For Int or Real data types you can add a validation. Possible validations are:
>, >=, <, <= followed by a number, e.g. ">=0"
"required" or "optional" if a value must be entered or can be empty
empty string "" if no validation is required
All required and configurable properties for the integrated algorithm should be defined in a json file using the format described above. Apart from that, no further adjustments are necessary in the "gui_properties_configuration" folder.
You will find a more detailed example json file at the end of this manual. (cf. Section 10.4.2.3, “Example GUI configuration json”)
In the "source" folder, the algorithm logic must be defined. Two files are mandatory, which will be the entry point for the Optimizer Component. One file must be named "python_path", which only contains one single line that points to the executable of a python installation. The other file must be named "generic_optimizer.py". This script must call your own optimizer method. In this script you can use the Optimizer Algorithm API. The API contains three modules. Import the modules as follows:
from RCE_Optimizer_API import configuration from RCE_Optimizer_API import evaluation from RCE_Optimizer_API import result
Module Description:
configuration: This module contains all information that is needed to configure the optimization method. You can get the design variables names and counts and the objective names and weigths. Furthermore you can access the property values configured by the user in the GUI.
evaluation: Use this module you start an evaluation run in RCE and get the result of each evaluation and end the optimizer.
result: If an evaluation is done, it generates a new result object. It contains objective and constraint values, their gradients and the failed inputs from RCE and provides methods to access them. The result object is lost at the next evaluation unless it is explicitly saved somewhere.
For detailed information on the modules and the included methods see Section Section 10.4.3, “Module Description”
{
"methodName" : "Name of method",
"optimizerPackage" : "generic",
"commonSettings" : {
...
},
"specificSettings" : {
"textExample" : {
"GuiName" : "Enter Value:",
"GuiOrder" : "1",
"dataType" : "Real",
"SWTWidget" : "Text",
"DefaultValue" : "1.0",
"Value" : "",
"Validation" : "<=1.0"
},
"comboExample" : {
"GuiName" : "Select parameter",
"GuiOrder" : "2",
"dataType" : "String",
"SWTWidget" : "Combo",
"Choices" : "choice1,choice2,choice3",
"DefaultValue" : "choice1",
"Value" : ""
},
"checkboxExample" : {
"GuiName" : "Any flag:",
"GuiOrder" : "3",
"dataType" : "Bool",
"SWTWidget" : "Check",
"DefaultValue" : "false",
"Value" : ""
}
},
"responsesSettings" : {
...
}
}
Property names must be unique on each tab. Otherwise the last configuration is used.
The field "GuiOrder" is optional. Use this field to specify or change easily the order of the widgets in the GUI.
Table 10.1. configuration.py
| Method | Description |
|---|---|
| def get_algorithm() | Returns the selected algorithm |
| def get_design_variable_count() | Returns the number of design variables |
| def get_design_variable_names() | Returns a list of variable names |
| def get_design_variable_max_values() | Returns a dictionary of the variables and their corresponding upper bound |
| def get_design_variable_min_values() | Returns a dictionary of the variables and their corresponding lower bound |
| def get_design_variable_max_value(variable_name) | Returns the upper bound of the given variable "variable_name" |
| def get_design_variable_min_value(variable_name) | Returns the lower bound of the given variable "variable_name" |
| def get_start_values() | Returns a dictionary of the variables and their corresponding start values |
| def get_start_value(variable_name) | Returns the start value of the given variable "variable_name" |
| def get_step_values() | Returns a dictionary of the variables and their corresponding start values |
| def is_discrete_variable(variable_name) | Returns whether the given variable "variable_name" is discrete or not |
| def get_constraint_names() | Returns a list of constraint names |
| def get_constraint_max_values() | Returns a dictionary of the constraints and their corresponding upper bound |
| def get_constraint_min_values() | Returns a dictionary of the constraints and their corresponding lower bound |
| def get_constraint_max_value(constraint_name) | Returns the upper bound of the given constraint "constraint_name" |
| def get_constraint_min_value(constraint_name) | Returns the lower bound of the given constraint "constraint_name" |
| def get_objective_names() | Returns a list of objectives names |
| def get_objective_weights() | Returns a dictionary of the objectives and their corresponding weight |
| def get_optimization_targets() | Returns a dictionary of the objectives and their corresponding optimization target |
| def get_optimization_target(name) | Returns the optimization target of the given objective "name" or None if an objective "name" does not exists |
| def get_common_properties() | Returns a dictionary of all common properties and their corresponding values |
| def get_common_property(name) | Returns the value of the given common property "name" or None if a property "name" does not exists |
| def get_common_property_keys() | Returns a list of all common property keys |
| def get_specific_properties() | Returns a dictionary of all specific properties and their corresponding values |
| def get_specific_property(name) | Returns the value of the given specific property "name" or None if a property "name" does not exists |
| def get_specific_property_keys() | Returns a list of all specific property keys |
| def get_responses_properties() | Returns a dictionary of all responses properties and their corresponding values |
| def get_responses_property(name) | Returns the value of the given responses property "name" or None if a property "name" does not exists |
| def get_responses_property_keys() | Returns a list of all responses property keys |
Table 10.2. evaluation.json
| Method | Description |
|---|---|
| def evaluate(number_evaluation, design_variables, grad_request = False) | Starts the evaluation run with the given run number, designs
variables and a boolean whether gradients are requested or not
(default value is False). The result object of the current run
is returned. Note: The design variables are handed over in an alphabetically sorted list as displayed in the Properties view of RCE's GUI. Be aware that uppercase is treated before lowercase variable names. Vectors are passed entry-wise. Example: Given the following design variables "Var1", "Vec" and "var2" with the values 1, [2,3,4] and 2 in evaluation run number 5. Start the evaluation run with evaluate(5,[1,2,3,4,2]). |
| def finalize(optimal_evaluation_number) | Ends the Optimization with the given run number as the optimal run. The optimal values are written to the outputs. |
Table 10.3. result.py
| Method | Description |
|---|---|
| def get_constraint_gradient(constraint_name) | Returns the gradient value of the given constraint "constraint_name" or None if the constraint does not exists or no gradient is defined |
| def get_constraint_value(constraint_name) | Returns the value of the given constraint "constraint_name" or None if a constraint "constraint_name" does not exists |
| def get_failed() | Returns a list of the failed optimization runs |
| def get_objective_gradient(objective_name) | Returns the gradient value of the given objective "objective_name" or None if the objective does not exists or no gradient is defined |
| def get_objective_value(objective_name) | Returns the value of the given objective "objective_name" or None if the objective does not exists |
| def has_gradient(name) | Returns True if the given input "name" has a gradient defined, False otherwise |