Python Optimizer Technique

The Python Optimizer technique provides a convenient way for you to integrate your own optimization algorithm, developed using Python outside of Isight, and still make use of Isight's integration and automation capabilities.

This technique requires you to implement a defined set of functions in your Python routine. All the functions must be mandatorily implemented. When Isight infrastructure calls these functions, either a design time interface object or a runtime interface object, as applicable, is passed to the functions as an argument. The APIs available on these interface objects are documented in this section subsequently.

Example python routines and example models that use these routines are available in the <Isight_install_directory>/<operating_system>/examples/models/components/optimization directory. These routines illustrate how you could go about developing your own routines.

This page discusses:

Contract of functions required to be implemented in Python routine
APIs exposed by the design time interface object
APIs exposed by discrete limit object
APIs exposed by the runtime interface object
APIs exposed by Result object
APIs exposed by Variable, Output, Constraint, and Objective objects

Contract of functions required to be implemented in Python routine


Function	What should you implement in this function?	When is it called?
`defineTechniqueOptions(dt_interface)`	You should add custom technique options, if any, for the Optimization algorithm using the API exposed by the design time interface object. The specified technique options will be added to the technique and will become visible in the Technique Options table in the Optimization component editor.	When you select a Python Optimizer Routine from the Optimization editor When the `set("pythonOptTechnique", String filePath)` method of Optimization Component API is called
`optimize(rt_interface)`	You should implement your algorithm or integrate an external algorithm in this function. The Optimization problem formulation (technique options, design variables, constraints, and objectives) can be accessed using the appropriate API exposed by runtime interface object, which is passed as an argument to this function. APIs are available to trigger execution of sub-flow runs using Isight infrastructure, which also return the result of the execution. Certain other APIs are also available, which are documented in the following sections. This function must return a boolean value - `True` indicates that the optimization was successful and `False` indicates that it failed.	When a model employing this technique is executed.

APIs exposed by the design time interface object


Method	Arguments (in the required sequence)	Return value	Description
`addOption()`	`name`: name of the custom technique option as a `string`. `type`: data type of the custom technique option as a `string`. It must be one of the following: "Integer", "Real", "Boolean", and "String". `defaultValue`: the default value of the custom technique option; must be provided as a `string`. `limit`: an object representing either a discrete limit or a range limit.	`None`	Adds a new custom technique option having the specified name, data type, default value, and limit. You should use either `createDiscreteLimit()` or `createRangeLimit()` API to create a limit object. To create an unbounded option, you should use a range limit that has no bounds. Refer the documentation of `createRangeLimit()` API for more details.
`createDiscreteLimit()`	This method does not take any arguments.	A discrete limit object.	Returns a discrete limit object. At the time of creation, this object does not contain any `allowed value`. You should add the `allowed values` to this object using `addAllowedValue()` API. For more details, refer the documentation of discrete limit object, available below. A discrete limit can be used for a technique option that has any of "Integer", "Real", "String", or "Boolean" data type.
`createRangeLimit()`	`lowerBound`: the lower bound value as a `string`. `lbInclusive`: whether or not the lower bound value itself is allowed as a value of the technique option. It should be a boolean value: `True` or `False`. `upperBound`: the upper bound value as a `string`. `ubInclusive`: whether or not the upper bound value itself is allowed as a value of the technique option. It should be a boolean value: `True` or `False`.	A range limit object	Returns a range limit object. The returned object is immutable. It makes sense to use range limit for technique options that have only "Integer" or "Real" data types. If `lowerBound` and/or `upperBound` is specified as `None`, the technique option is treated as unbounded on the corresponding end of the range.
`setCanHandleDesignPointEvaluationFailure()`	`canHandle`: whether or not the Python routine can handle failure of design point execution. It should be a `boolean` value: `True` or `False`.	`None`	Informs the Isight infrastructure about the capability, or lack thereof, of the Python routine that you have developed, to handle design point evaluation (i.e. sub-flow execution) failure. If your routine indicates that it cannot handle design point evaluation failure, then Isight infrastructure will fail the execution of Optimization component on the first sub-flow execution failure. Otherwise, the behavior of Isight infrastructure will depend on "Max Failed Runs" technique option.
`logDebug()`	`message`: the message to be logged as a `string` value	`None`	Logs the message to Isight system log as a debug-level message.
`logInfo()`	`message`: the message to be logged as a `string` value	`None`	Logs the message to Isight system log as an information-level message.
`logWarn()`	`message`: the message to be logged as a `string` value	`None`	Logs the message to Isight system log as a warning-level message.
`logError()`	`message`: the message to be logged as a `string` value	`None`	Logs the message to Isight system log as an error-level message.
`logSysError()`	`message`: the message to be logged as a `string` value	`None`	Logs the message to Isight system log as a system-error-level message.
`logAlways()`	`message`: the message to be logged as a `string` value	`None`	Logs the message to Isight system log as an always-level message.

APIs exposed by discrete limit object


Method	Arguments (in the required sequence)	Return value	Description
`addAllowedValue()`	`allowedValue`: a specific value to be permitted as an allowed value.	The discrete limit object itself on which this method is called.	Adds the supplied value as an allowed value to this discrete limit object, and returns this object. This allows chaining of multiple calls to `addAllowedValue()` method. For example, `limit.addAllowedValue("1").addAllowedValue("3")`.

APIs exposed by the runtime interface object


Member	Type	Arguments (in the required sequence)	Return value	Description
`rt_interface.technique_options`	Data member	N.A.	A dictionary of technique option names mapped to option values.	A dictionary of technique option names mapped to the corresponding technique option values. Both the names and values are `string` values.
`rt_interface.start_point`	Data member	N.A.	An array of Strings.	An array of `string` values representing the starting point input vector. The order of input values in the array is the same as the order of inputs in `rt_interface.variables` list.
`rt_interface.variables`	Data member	N.A.	A list of objects, each representing an optimization variable.	A list of objects, each representing an input variable. Each object encapsulates the configuration of the corresponding input variable in Isight Optimization component. Variable objects are immutable. For more details about the API exposed by variable objects, refer the documentation of variable objects, available below.
`rt_interface.outputs`	Data member	N.A.	A list of objects, each representing an output variable.	A list of objects, each representing an output variable. It is a union set of constraints and objectives. Each object encapsulates the configuration of the corresponding output variable in Isight Optimization component. Output objects are immutable. For more details about the API exposed by output objects, refer the documentation of variable object, available below.
`rt_interface.constraints`	Data member	N.A.	A list of objects, each representing a constraint.	A list of objects, each representing a constraint. Each object encapsulates the configuration of the corresponding constraint in Isight Optimization component. Constraint objects are immutable. For more details about the API exposed by constraint objects, refer the documentation of variable objects, available below.
`rt_interface.objectives`	Data member	N.A.	A list of objects, each representing an objective.	A list of objects, each representing an objective. Each object encapsulates the configuration of the corresponding objective in Isight Optimization component. Objective objects are immutable. For more details about the API exposed by objective objects, refer the documentation of variable objects, available below.
`evaluateDesignPoint()`	Method	`inputs`: A list of float values. It represent one single input vector (design point).	This method returns Result object.	Triggers evaluation of a single design point that is a single sub-flow execution - using Isight infrastructure. This method blocks until the sub-flow execution completes. For more details about the API exposed by Result objects, refer the documentation of Result objects, available below.
`evaluateDesignPointSet()`	Method	`all_inputs`: A list of float values. It represents potentially multiple vectors (design points) as a flattened list	This method returns a list of Result objects.	Triggers evaluation of all the design points in parallel using Isight infrastructure. This methord blocks until the execution of all the sub-flows is completed. It returns a list of objects, each representing the result of the corresponding sub-flow execution. For more details about the API exposed by Result objects, refer the documentation of Result objects, available below.
`writeParetoFile()`	Method	`pareto_points`: a list-like of object representing the set of pareto points. Each element of the list should itself be a list-like object representing objective values for one pareto point. The objective values are in the same order in which objective objects are arranged in `rt_interface.objectives`.	None	Writes a pareto file containing the Pareto front computed by the python routine.
`setSummaryToIsight()`	Method	`Summary`: An HTML markup `string` that may be added to the body of HTML summary page of optimization component.	None	Requests Isight infrastructure to add the specifed HTML markup to the post-processing summary of the Optimization component. The supplied summary must be a valid HTML mark up.
`logDebug()`	Method	`message`: The message to be logged as a `string` value	`None`	Logs the message to Isight system log or job log, as applicable, as a debug-level message.
`logInfo()`	Method	`message`: The message to be logged as a `string` value	`None`	Logs the message to Isight system log or job log, as applicable, as an information-level message.
`logWarn()`	Method	`message`: the message to be logged as a `string` value	`None`	Logs the message to Isight system log or job log, as applicable, as a warning-level message.
`logError()`	Method	`message`: the message to be logged as a `string` value	`None`	Logs the message to Isight system log or job log, as applicable, as an error-level message.
`logSysError()`	Method	`message`: the message to be logged as a `string` value	`None`	Logs the message to Isight system log or job log, as applicable, as a system-error-level message.
`logAlways()`	Method	`message`: the message to be logged as a `string` value	`None`	Logs the message to Isight system log or job log, as applicable, as an always-level message.

APIs exposed by Result object


Method	Arguments (in the required sequence)	Return value	Description
`isSuccess()`	This method does not take any arguments.	A `boolean` value indicating whether the particular sub-flow execution completed succesfully, or it failed.	Returns a `boolean` value indicating whether the particular sub-flow execution completed successfully, or it failed.
`getInputVector()`	This method does not take any arguments.	A list-like object representing the input vector.	Returns a list-like object representing the input vector (design point) to be evaluated.
`getOutputVector()`	This method does not take any arguments.	A list-like object representing the output vector.	Returns a list-like object representing the output vector, that is, the result of the sub-flow execution.
`getObjective()`	This method does not take any arguments.	A float value representing the objective function value computed by Isight infrastructure for the design point.	Returns the objective function value computed by Isight infrastructure for the design point.
`getPenalty()`	This method does not take any arguments.	A float value representing the penalty value computed by Isight infrastructure for the design point.	Returns the penalty value computed by Isight infrastructure for the design point.

APIs exposed by Variable, Output, Constraint, and Objective objects


Method	Arguments (in the required sequence)	Return value	Description
`getName()`	This method does not take any arguments.	Name of the variable, output, constraint, objective, as the case may be, as a `string` value.	Returns the name of the variable, output, constraint, objective, as the case may be.
`getType()`	This method does not take any arguments.	Type of the variable, output, constraint, objective, as the case may be, as a `string` value.	Returns the data type of the variable, output, constraint, objective, as the case may be. It will be either "Integer" or "Real" because "String" or "Boolean" type parameters are not supported by the Python Optimizer technique.
`getAttributes()`	This method does not take any arguments.	This method returns the Map, which containts Attributes data set by user into optimization component UI. Where attribute name as key and attribute value as value. Data type is string for key and value. A dictionary of attributes names mapped to attribute values.	A dictionary of attributes names mapped to the corresponding attribute values. Both the attribute names and attribute values are `string` values. Note that, variables, constraints, and objectives possess different sets of attributes as documented below. Variable objects can have following attributes: `Lower Bound, Upper Bound, Allowed values, Scale Factor.` Constraint objects can have following attributes: `Lower Bound, Upper Bound, Target, Scale Factor, Weight Factor.` Objective objects can have following attributes: `Direction, Target, Scale Factor, Weight Factor.` Output objects can also have attributes which is a super set of the attribues that are available on Variable, constraint, and objective objects. However, generally you would not access the attributes of output objects. The primary use of `rt_interfaqce.outputs` list-like object is to determine the position of a specific output in the output vector, so that you can access the value for computing constraint and objective functions in your python code.