| 9 | | context and returns a pointer to it. The context can be updated |
| 10 | | by calling functions like {{{RpOptimAddParamNumber}}} to define various |
| | 9 | context and returns a pointer to it. The ''pluginDefn'' describes the |
| | 10 | underlying optimization method; right now, there is only one definition |
| | 11 | for pgapack, but others could be added later on at the top of {{{rp_optimizer_tcl.c}}}. |
| | 12 | |
| | 13 | Once created, an optimization context can be updated by calling |
| | 14 | functions like {{{RpOptimAddParamNumber}}} to define various |
| 54 | | The input values for the evaluation are contained within the ''values'' |
| 55 | | array. Each value has a name, a type, and a value contained within a union. |
| 56 | | Here is an example of an {{{RpOptimEvaluator}}} function that starts off by extracting |
| 57 | | a number called "a" from the list of input values: |
| 58 | | {{{ |
| 59 | | RpOptimStatus |
| 60 | | GetValue(values, numValues, fitnessPtr) |
| 61 | | RpOptimParam **values; /* array of input values */ |
| 62 | | int numValues; /* number of values on the list */ |
| 63 | | double *fitnessPtr; /* returns: value of fitness */ |
| 64 | | { |
| 65 | | double a = 0.0; |
| 66 | | |
| 67 | | for (n=0; n < numValues; n++) { |
| 68 | | if (strcmp(values[n]->name,"a") == 0 && values[n]->type == RP_OPTIMPARAM_NUMBER) { |
| 69 | | a = values[n]->value.num; |
| 70 | | } |
| 71 | | ... |
| 72 | | }}} |
| 73 | | Each call to the evaluator function should return RP_OPTIM_SUCCESS |
| 74 | | if it was able to compute a fitness function value based on the |
| 75 | | inputs, or RP_OPTIM_FAILURE if something went wrong for that set |
| 76 | | of inputs values. |
| 77 | | |
| 78 | | The call to {{{RpOptimPerform}}} also returns a success/failure |
| 79 | | status. If an optimum value is found within the limit |
| 80 | | on the number of runs, then {{{RpOptimPerform}}} returns RP_OPTIM_SUCCESS. |
| 81 | | Values for the optimum input parameters are returned through the |
| 82 | | ''paramList'' within the context. If the optimization fails, this |
| 83 | | function returns RP_OPTIM_FAILURE. |
| 84 | | |
| | 55 | ||!RpOptimEnv* || envPtr || context for this optimization || |
| | 56 | ||char* || name || name of parameter to be deleted || |
| | 70 | == Plug-in Definitions == |
| | 71 | |
| | 72 | Optimization libraries such as PGApack should be integrated into this package |
| | 73 | via the plug-in mechanism. Each plug-in is defined by a record hard-coded |
| | 74 | at the top of the [source:trunk/optimizer/src/rp_optimizer_tcl.c] file. |
| | 75 | Right now, it looks like this: |
| | 76 | |
| | 77 | {{{ |
| | 78 | static RpOptimPlugin rpOptimPlugins[] = { |
| | 79 | {"pgapack", PgapackInit, PgapackRun, PgapackCleanup, &PgapackOptions}, |
| | 80 | {NULL, NULL, NULL}, |
| | 81 | }; |
| | 82 | }}} |
| | 83 | |
| | 84 | The first element is the name of the optimization package. |
| | 85 | |
| | 86 | The second is the name of an initialization routine that is called whenever |
| | 87 | an optimizer object is created, to initialize configuration parameters |
| | 88 | associated with the package. These are things like the population size, |
| | 89 | maximum number of runs, etc., that can be configured to control the optimization. |
| | 90 | |
| | 91 | The third argument is the routine that runs the core of the optimization. It |
| | 92 | takes as arguments the optimization environment, a function to handle evaluations |
| | 93 | (runs), and a string representing the fitness function being evaluated. It |
| | 94 | returns a status of RP_OPTIM_SUCCESS if optimization was achieved, and RP_OPTIM_FAILURE |
| | 95 | or RP_OPTIM_ABORTED if something goes wrong. |
| | 96 | |
| | 97 | The fourth argument is a clean-up routine called whenever the optimization |
| | 98 | environment is deleted to clean up memory allocated during the initialization |
| | 99 | routine. |
| | 100 | |
| | 101 | The fifth argument is a list of configuration options that represent the knobs |
| | 102 | on the optimization algorithm that can be tweaked. Each option in this list |
| | 103 | is associated with an element of the data structure allocated during the |
| | 104 | initialization routine. |
| | 105 | |
| | 106 | ---- |
| | 107 | |
| 99 | | Here is a quick example of the optimization API in action. (For complete details, see the test example [source:trunk/optimizer/src/test.c]) |
| | 109 | Here is a quick example of the optimization API in action. |
| | 110 | Note that this API has corresponding [wiki:OptimizationTclApi Tcl bindings], |
| | 111 | and those bindings are normally used to create an optimization program, such |
| | 112 | as the example program in [source:trunk/optimizer/examples/simple.tcl]. |
| | 113 | The following isn't really a very good or complete example, but just |
| | 114 | a quick example to show the API in action. |
| 105 | | envPtr = RpOptimCreate( |
| 106 | | RpOptimAddParamNumber(envPtr, "a", 0.0, 1.0); |
| 107 | | RpOptimAddParamNumber(envPtr, "b", 1.0, 10.0); |
| 108 | | RpOptimAddParamString(envPtr, "func", funcValues); |
| | 125 | envPtr = RpOptimCreate(rpOptimPlugins[0]); |
| | 126 | numParam = (RpOptimParamNumber*)RpOptimAddParamNumber(envPtr, "a"); |
| | 127 | numParam->min = 0.0; |
| | 128 | numParam->max = 1.5; |
