## Optimization Algorithm API

### Basic Concepts

The RCE Optimization Algorithm API gives the user the possibility to integrate 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.

### How to integrate an algorithm into RCE

The location the API searches for algorithms is in the profile folder of RCE. The base path is:

`<profile>/integration/optimizer/`

In this path, every subfolder has a certain structure to be recognized as optimizer integration. Two folders must exist, having the names "gui_properties_configuration" and "source". For all this, an example integration is available in the "examples" folder of the RCE installation. Copy it to your profile and you can use the example in RCE.

#### GUI Properties Definition

The "gui_properties_configuration" folder defines the elements of the algorithm to be shown in the Optimizer Component GUI. At first, there has to be a file named "algorithms.json". In this file, RCE looks up what algorithms should be defined. The structure of this file must always be:

    {
        "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" ],
                "SWTWidget": ["Text" | "Combo" ],
                "DefaultValue": "",
                "Value":"",
                "Validation":""
            }
        }
    }

The "optimizerPackage" must always have the value "generic", the "methodName" must have the same value as the method it defines. With the "specificSettings", all configurable data for the integrated method can be shown in the RCE GUI. Every property must have the following fields:

GuiName: The text that it shown in the properites dialog of the optimizer.

dataType: Represents what type of data the current property is. Valid values are:

- Int: An integer number

- Real: A float number

- String: A text

SWTWidget: This value defines what kind of selection 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 seperated list of the values, e.g. "Option 1, Option 2"

DefaultValue: This is the 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: This always must be an empty string ("")

Validation: If you have an Int or Real data type, you can add a validation for that. Valid values are:

- > , >=, <, <=: Followed by a number, e.g. ">=0"

- required , optional: Defines if a value must be entered or if it can be blank.

- "" (empty string): If no validation is required.

The options defined here should represent all configurable properties of the method.

These are all things that have to be done in the "gui_properties_configuration" folder.

#### Source Folder

The other folder that has to be there is the "source" folder. In this, 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 somehow. In this script, you are able to use the Optimizer Algorithm API. The API contains three modules that can be imported like this:

    from RCE_Optimizer_API import configuration
    from RCE_Optimizer_API import evaluation
    from RCE_Optimizer_API import result

An API example is in the example integration. What the modules do:

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. You can also access the property values configured by the user in the GUI.

evaluation: With this module you can start an evaluation run in RCE and get back the result of it. You can also tell RCE the optimal design set number in the end to finish the optimizer.

result: This is the result you get from the evaluation. It contains objective and constraint values, their gradients and the failed inputs from RCE.

If an evaluation is done, it generates a new result object. This will be lost on the next evaluation, if not stored somewhere else before.