Rappture Optimization Tcl Library
Rappture comes with a built-in optimization package that knows how to drive the inputs for any Rappture-based tool toward the optimum of a certain fitness function. The Tcl API for that library is as follows:
Rappture::optimizer ?name? ?-tool toolObject? ?-using pluginName?
Creates an optimizer context used to drive optimization. Each time this command is invoked, it creates a new optimizer object and its associated Tcl access command. If the name is specified, then the Tcl access command has that name; otherwise, a name of the form optimizerN is generated automatically. The optional -tool option sets the Rappture Tool object that will be driven by the optimization. If not specified initially, the tool must be specified later in the perform operation. The -using option sets the name of the underlying optimization package, which right now must be pgapack, but in the future may include other packages such as dakota.
name add number path ?-min minValue? ?-max maxValue?
Adds a number parameter, which is eventually used as an input to the optimization. The path represents the full Rappture path name for the parameter. The -min and -max options constrain the range of input values.
name add string path ?-values valueList?
Adds a string parameter, which is eventually used as an input to the optimization. The path represents the full Rappture path name for the parameter. The -values option sets the list of allowed values for the string.
name configure ?-option? ?value -option value...?
Configures the optimization settings associated with the optimizer specified via the -using option when the optimizer was first created. With no arguments, this command returns a list of all options and their current value in the form -option1 value1 -option2 value2 .... If a single option name is specified, then this command returns the current value for that option. Otherwise, this command takes a list of option/value pairs, and changes the options according to the given settings.
name get ?namePattern? ?-option?
Used to query the value of one or more optimization parameters. With no arguments, this command returns a list of all optimization parameters and their current settings in the form: {name type -option1 value1 -option2 value2 ...} {name type -option1 value1 -option2 value2 ...}. If the namePattern is specified, it is treated as a glob-style pattern and returns a list of parameters with matching names. If there is more than one matching parameter, the result has the form shown earlier. If there is a single matching parameter, then the result has the form: type -option1 value1 -option2 value2 .... If the -option is also specified, then it returns the value for the specified option across all matching parameters. If two or more parameters match the namePattern, then the result will have the form: {name value} {name value} .... If a single parameter matches and the -option is specified, then the result is a single value.
name samples ?number?
Used to query information about the samples involved in an optimization. This can be called during the optimization (as part of the -updatecommand) or after the optimization is done. With no extra arguments, it returns the number of samples evaluated so far. Given a specific sample number (starting from 0), this returns a list of the form f p1 p2 p3 ..., where f is the value of the fitness function for that sample, and p1, p2, p3, ..., are the values of the input parameters.
name perform ?-tool toolObject? ?-fitness fitnessExpr? ?-updatecommand script?
Starts an optimization run. The run begins launching simulation jobs by telling the toolObject to {{run}} with a series of input values. The fitnessExpr represents the quantity being optimized. In the future, it could be an arbitrary mathematical expression; right now, it must be the Rappture path to a numeric output quantity in the result generated by the tool. The update script is executed after each tool execution to keep the runtime environment up-to-date, and to see if the user has asked to abort the operation. The name of the Rappture::library object containing results from the most recent run is appended to the script as an argument. That way, the script can inspect or report the new result.
The result of this command is as follows:
success param1 value1 param2 value2 ... successful optimization with resulting optimized values for all input parameters failure optimization failed aborted optimization aborted by the user
name using
Returns a list of one or two elements giving information about what resources the optimizer is using. The first element is the name of the plug-in handling the optimization. This is usually pgapack, but other plug-ins may be added later. The second element is the name of the -tool specified when the optimizer was created. If a tool was not specified, then there is no second element.
Example
Here's a simple example showing the Tcl API in action. A more complete example can be found in trunk/optimizer/examples/simple.tcl.
package require Itcl
package require Rappture
package require RapptureGUI
package require RapptureOptimizer
set xmlobj [Rappture::library tool.xml]
set tool [Rappture::Tool ::#auto $xmlobj .]
Rappture::optimizer optim -tool $tool -using pgapack
optim add number input.number(x1) -min -2 -max 2
optim add number input.number(x2) -min -2 -max 2
optim configure -operation minimize -popsize 100 -maxruns 200
set status [optim perform \
-fitness output.number(f).current \
-updatecommand {puts "checking"}]
puts "done: $status"
