source: trunk/packages/optimizer/src/rp_optimizer.h @ 1052

Last change on this file since 1052 was 899, checked in by mmc, 15 years ago

Added a -fitness option to the "perform" operation. Right now, you can
specify just the name of an output quantity, and that quantity can be
minimized or maximized. In the future, there should be an expression
parser so you can enter any function of Rappture quantities.

Fixed up the example so that it runs the Rosenbrock function, which is
difficult to minimize. Added a visualize.tcl script, so you can visualize
the output from many different runXXXX.xml files.

File size: 5.0 KB
Line 
1/*
2 * ----------------------------------------------------------------------
3 *  rp_optimizer
4 *
5 *  This is the C language API for the optimization package in
6 *  Rappture.  It lets you set up an optimization of some fitness
7 *  function with respect to a set of inputs.
8 *
9 * ======================================================================
10 *  AUTHOR:  Michael McLennan, Purdue University
11 *  Copyright (c) 2008  Purdue Research Foundation
12 *
13 *  See the file "license.terms" for information on usage and
14 *  redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.
15 * ======================================================================
16 */
17#ifndef RP_OPTIMIZER
18#define RP_OPTIMIZER
19
20#include <tcl.h>
21#include <math.h>
22#include <float.h>
23#include <string.h>
24#include <malloc.h>
25#include "rp_tcloptions.h"
26
27/*
28 * General-purpose allocation/cleanup routines:
29 * These are used, for example, for the plug-in architecture.
30 */
31typedef ClientData (RpOptimInit)_ANSI_ARGS_(());
32typedef void (RpOptimCleanup)_ANSI_ARGS_((ClientData cdata));
33
34/*
35 * During each optimization, a function of the following type is
36 * called again and again to evaluate input parameters and compute
37 * the fitness function.
38 */
39typedef enum {
40    RP_OPTIM_SUCCESS=0, RP_OPTIM_UNKNOWN, RP_OPTIM_FAILURE, RP_OPTIM_ABORTED
41} RpOptimStatus;
42
43struct RpOptimEnv;   /* defined below */
44struct RpOptimParam;
45
46typedef RpOptimStatus (RpOptimEvaluator) _ANSI_ARGS_((
47    struct RpOptimEnv *envPtr, struct RpOptimParam *values, int numValues,
48    double *fitnessPtr));
49
50typedef RpOptimStatus (RpOptimHandler) _ANSI_ARGS_((
51    struct RpOptimEnv *envPtr, RpOptimEvaluator *evalProc,
52    char *fitnessExpr));
53
54/*
55 * Each optimization package is plugged in to this infrastructure
56 * by defining the following data at the top of rp_optimizer_tcl.c
57 */
58typedef struct RpOptimPlugin {
59    char *name;                   /* name of this package for -using */
60    RpOptimInit *initProc;        /* initialization routine */
61    RpOptimHandler *runProc;      /* handles the core optimization */
62    RpOptimCleanup *cleanupProc;  /* cleanup routine */
63    RpTclOption *optionSpec;      /* specs for config options */
64} RpOptimPlugin;
65
66/*
67 * This is the basic definition for each parameter within an optimization.
68 * Each parameter has a name, type, and value.  The value is important
69 * at the end of an optimization.  It is either the final value, or the
70 * value where we left off when the optimization was terminated.
71 */
72typedef enum {
73    RP_OPTIMPARAM_NUMBER, RP_OPTIMPARAM_STRING
74} RpOptimParamType;
75
76typedef struct RpDiscreteString {
77    int num;                        /* integer representing this string */
78    char *str;                      /* actual string selected */
79} RpDiscreteString;
80
81typedef struct RpOptimParam {
82    char *name;                     /* name of this parameter */
83    RpOptimParamType type;          /* paramter type -- number, string, etc */
84    union {
85        double dval;                /* slot for number value */
86        int ival;                   /* slot for integer value */
87        RpDiscreteString sval;      /* slot for string value */
88    } value;
89} RpOptimParam;
90
91/*
92 * NUMBER PARAMETERS have additional min/max values as constraints.
93 */
94typedef struct RpOptimParamNumber {
95    RpOptimParam base;              /* basic parameter info */
96    double min;                     /* optimization constraint: min value */
97    double max;                     /* optimization constraint: max value */
98} RpOptimParamNumber;
99
100/*
101 * STRING PARAMETERS have a set of allowed values.
102 */
103typedef struct RpOptimParamString {
104    RpOptimParam base;              /* basic parameter info */
105    char **values;                  /* array of allowed values */
106    int numValues;                  /* number of allowed values */
107} RpOptimParamString;
108
109/*
110 * Each optimization problem is represented by a context that includes
111 * the parameters that will be varied.
112 */
113typedef struct RpOptimEnv {
114    RpOptimPlugin *pluginDefn;      /* plug-in handling this optimization */
115    ClientData pluginData;          /* data created by plugin init routine */
116    RpOptimEvaluator *evalProc;     /* called during optimization to do run */
117    char *fitnessExpr;              /* fitness function in string form */
118    ClientData toolData;            /* data used during tool execution */
119    RpOptimParam **paramList;       /* list of input parameters to vary */
120    int numParams;                  /* current number of parameters */
121    int maxParams;                  /* storage for this many paramters */
122} RpOptimEnv;
123
124/*
125 *  Here are the functions in the API:
126 */
127EXTERN RpOptimEnv* RpOptimCreate _ANSI_ARGS_((RpOptimPlugin *pluginDefn));
128
129EXTERN RpOptimParam* RpOptimAddParamNumber _ANSI_ARGS_((RpOptimEnv *envPtr,
130    char *name));
131
132EXTERN RpOptimParam* RpOptimAddParamString _ANSI_ARGS_((RpOptimEnv *envPtr,
133    char *name));
134
135EXTERN RpOptimParam* RpOptimFindParam _ANSI_ARGS_((RpOptimEnv *envPtr,
136    char *name));
137
138EXTERN void RpOptimDeleteParam _ANSI_ARGS_((RpOptimEnv *envPtr, char *name));
139
140EXTERN void RpOptimDelete _ANSI_ARGS_((RpOptimEnv *envPtr));
141
142#endif
Note: See TracBrowser for help on using the repository browser.