<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<sect1 id="optimization_algorithm_api">
    <title>Optimization Algorithm API</title>
    <sect2>
        <title>Basic Concepts</title>
        <para>The RCE Optimization Algorithm API gives the user the possibility, to integrate his
            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. </para>
    </sect2>
    <sect2>
        <title>How to integrate an algorithm into RCE</title>
        <para>The location the API searches for algorithms is in the profile folder of RCE. The base
            path is:</para>
        <para><code>&lt;profile>/integration/optimizer/</code></para>
        <para>In this path, every subfolder has a certain structure to be recognized as optimizer
            integration. Two folders must exist, having the names "<emphasis role="italic"
                >gui_properties_configuration</emphasis>" and "<emphasis role="italic"
                >source</emphasis>". For all this, an example integration is available in the
                "<emphasis role="italic">examples</emphasis>" folder of the RCE installation. Copy
            it to your profile and you can use the example in RCE.</para>
        <sect3>
            <title>GUI Properties Definition</title>
            <para>The "<emphasis role="italic">gui_properties_configuration</emphasis>" folder
                defines the elements of the algorithm to be shown in the Optimizer Component GUI. At
                first, there has to be a file named "<emphasis role="italic"
                    >algorithms.json</emphasis>". In this file, RCE looks up what algorithms should
                be defined. The structure of this file must always be:</para>
            <para>
                <programlisting>{
    "Name of algorithm":"name of json file for algorithm"
}</programlisting>
            </para>
            <para>For example: </para>
            <para>
                <programlisting>{
	"Name of method1" : "method1",
	"Name of method2" : "method2"
}</programlisting>
            </para>
            <para>where "<emphasis role="italic">method1.json</emphasis>" and "<emphasis
                    role="italic">method2.json</emphasis>" exist in the same directory. </para>
            <para>The method files also have to be in a certain format which looks like this:</para>
            <para>
                <programlisting>{
    "methodName":"Name of method",
    "optimizerPackage":"generic",
    "specificSettings":{
        "propertyName":{
            "GuiName":"Name shown in optimizer GUI",
            "dataType": ["Int" | "Real" | "String" ],
            "SWTWidget": ["Text" | "Combo" ],
            "DefaultValue": "",
            "Value":"",
            "Validation":""
        }
	}
}</programlisting>
            </para>
            <para>The "<emphasis role="italic">optimizerPackage</emphasis>" must always have the
                value "<emphasis role="italic">generic</emphasis>", the "<emphasis role="italic"
                    >methodName</emphasis>" must have the same value as the method it defines. With
                the "<emphasis role="italic">specificSettings</emphasis>", all configurable data for
                the integrated method can be shown in the RCE GUI. Every property must have the
                following fields:</para>
            <para><emphasis role="bold">GuiName</emphasis>: The text that it shown in the properites
                dialog of the optimizer.</para>
            <para><emphasis role="bold">dataType</emphasis>: Represents what type of data the
                current property is. Valid values are: </para>
            <para>
                <itemizedlist>
                    <listitem>
                        <para><emphasis role="bold">Int</emphasis>: An integer number </para>
                    </listitem>
                    <listitem>
                        <para><emphasis role="bold">Real</emphasis>: A float number </para>
                    </listitem>
                    <listitem>
                        <para><emphasis role="bold">String</emphasis>: A text</para>
                    </listitem>
                </itemizedlist>
            </para>
            <para><emphasis role="bold">SWTWidget</emphasis>:  This value defines what kind of
                selection element is used for the property. Valid values are:</para>
            <para>
                <itemizedlist>
                    <listitem>
                        <para><emphasis role="bold">Text</emphasis>: A text box where the user can
                            enter any string</para>
                    </listitem>
                    <listitem>
                        <para><emphasis role="bold">Combo</emphasis>: A dropdown menue with pre
                            defined values. When using the Combo, you have to define the values to
                            be shown, using:</para>
                        <para>
                            <itemizedlist>
                                <listitem>
                                    <para><emphasis role="bold">Choices</emphasis>: A comma
                                        seperated list of the values, e.g. "Option 1, Option
                                        2"</para>
                                </listitem>
                            </itemizedlist>
                        </para>
                    </listitem>
                </itemizedlist>
            </para>
            <para><emphasis role="bold">DefaultValue</emphasis>: This is the values that is chosen
                if the user does not manually enter a value for the property. For Combos, this must
                be one of the "Choices"</para>
            <para><emphasis role="bold">Value</emphasis>: This always must be an empty string
                ("")</para>
            <para><emphasis role="bold">Validation</emphasis>: If you have an Int or Real data type,
                you can add a validation for that. Valid values are:</para>
            <para>
                <itemizedlist>
                    <listitem>
                        <para><emphasis role="bold">> , >=, &lt;, &lt;=</emphasis>: Followed by a
                            number, e.g. ">=0"</para>
                    </listitem>
                    <listitem>
                        <para><emphasis role="bold">required , optional</emphasis>: Defines if a
                            value must be entered or if it can be blank.</para>
                    </listitem>
                    <listitem>
                        <para><emphasis role="bold">""</emphasis>: If no validation is
                            required.</para>
                    </listitem>
                </itemizedlist>
            </para>
            <para>With this options, all configurable properties of the method should be integrated
                for RCE. </para>
            <para>This are all things that have to be done in the "<emphasis role="italic"
                    >gui_properties_configuration</emphasis>" folder. </para>
        </sect3>
        <sect3>
            <title>Source Folder</title>
            <para>The other folder that has to be there is the "<emphasis role="italic"
                    >source</emphasis>" folder. In this, only one file is mandatory, which will be
                the entry point for the Optimizer Component. This file must be named "<emphasis
                    role="italic">generic_optimizer.py</emphasis>". This script must call your own
                optimizer method somehow and you are able to use the Optimizer Algorithm API. The
                API contains three modules that can be imported like this:</para>
            <para>
                <programlisting>from RCE_Optimizer_API import configuration
from RCE_Optimizer_API import evaluation
from RCE_Optimizer_API import result</programlisting>
            </para>
            <para>An API example is in the example integration. What the modules do:</para>
            <para><emphasis role="bold">configuration</emphasis>: This module contains all
                information that is needed to configure the optimization method. You can get the
                design variables names and counts, objective names, weigths and also the in the RCE
                GUI configured property values from the Optimizer GUI and more.</para>
            <para><emphasis role="bold">evaluation</emphasis>: 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.</para>
            <para><emphasis role="bold">result</emphasis>: This is the result you get from the
                evaluation. It contains objective and constraint values, their gradients and the
                failed inputs from RCE.</para>
            <para>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. </para>
        </sect3>
    </sect2>
</sect1>
