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; |