generic/compiler/rel_blackbox.h

#ifndef ASC_REL_BLACKBOX_H
#define ASC_REL_BLACKBOX_H
/* 
        note: blackbox equations support the form
                output[i] = f(input[j] for all j) foreach i
    which we calculate by calling yhat = f(x),
    and then residual is y-yhat.
*/

extern int BlackBoxCalcResidual(struct Instance *i, double *res, struct relation *r);

/** Compute standard form residual and gradient. 
See relation_util.h gradient functions
for additional notes on the gradient output array and varlist.
@param i the relation instance in question.
@param residual the residual computed (output).
@param gradient the gradient computed (output), an array as long as r->varlist
and with elements corresponding to the elements of varlist.
@param r the relation data from i.
*/
extern int BlackBoxCalcResidGrad(struct Instance *i, double *residual, double *gradient, struct relation *r);

/** Compute standard form gradient. 
See relation_util.h gradient functions
for additional notes on the gradient output array and varlist.
@param i the relation instance in question.
@param gradient the gradient computed (output), an array as long as r->varlist
and with elements corresponding to the elements of varlist.
@param r the relation data from i.
*/
extern int BlackBoxCalcGradient(struct Instance *i, double *gradient, struct relation *r);

/**
Return the output variable instance from r, assuming r is from a blackbox.
*/
extern struct Instance *BlackBoxGetOutputVar(struct relation *r);

/** All the relations evaluated in a single call to y=f(x) have this data in common.  */
struct BlackBoxCache { /* was extrelcache, sort of. */
    struct gl_list_t *formalArgList; /**< only passed on pre_slv */
    struct BBoxInterp interp; /**< userdata lives in here only */
    int32 inputsLen; /**< number of actual, not formal, inputs */
    int32 outputsLen; /**< number of actual, not formal, outputs. */
    int32 jacobianLen;
    int32 hessianLen;
    double *inputs; /**< aka x; previous input for func eval. */
    double *outputs; /**< aka yhat. previous output for func eval. */
    double *inputsJac; /**< aka x; previous input for gradient eval. */
    double *jacobian; /**< sensitivity dyhat/dx ; row major format; previous gradient output. */
    double *hessian; /**< undetermined format */
    int residCount; /**< number of calls made for y output. */
    int gradCount; /**< number of calls made for gradient. */
    int refCount; /* when to destroy */
};

/** All the elements of an array of blackbox relations resulting
from a single external statement have the BlackBoxCache in common, but
the varlist and lhs are unique to the specific relation.
If someone really needs a nodestamp, for some reason,
the 'common' pointer is unique to the set.
*/
struct BlackBoxData {
    struct BlackBoxCache *common;
    unsigned long *inputArgs;  /**< an array of indexes into the varlist;
                see notes elsewhere about why varlist
                may be shorter than arglist due to alias/ats.
                size is in common. */
    unsigned long lhsindex; /**< location of value yhati in C output array. */
    unsigned long lhsvar; /**< location of lhs var(yi) in varlist. */
};

/* make a blackboxdata unique to a single relation. */
extern struct BlackBoxData *CreateBlackBoxData(struct BlackBoxCache *common,
                    unsigned long lhsindex,
                    unsigned long lhsVarNumber);

/* called when destroying the relation containing b. */
extern void DestroyBlackBoxData(struct relation * rel, struct BlackBoxData *b);

/**
Returns an initialized common data for a blackbox relation array
with an initial refcount 1.
Call DeleteRefBlackBoxCache when done with the object, and
make a call to AddRef any time the pointer is stored in a 
persistent structure.
 @param inputsLen number of actual, not formal, inputs.
 @param outputsLen number of actual, not formal, outputs.
 @param formalArgs list of list of args, which will be copied.
*/
extern struct BlackBoxCache *CreateBlackBoxCache( int32 inputsLen, int32 outputsLen, struct gl_list_t *formalArgs);

/** make a persistent reference to b. */
extern void AddRefBlackBoxCache(struct BlackBoxCache *b);

/** remove a persistent reference to *b.
 sets *b to null before returning.
 deallocates **b if refcount has dropped to 0.
 */
extern void DeleteRefBlackBoxCache(struct relation *rel, struct BlackBoxCache **b);


#endif /* ASC_REL_BLACKBOX_H */
1	johnpye	908	#ifndef ASC_REL_BLACKBOX_H
2			#define ASC_REL_BLACKBOX_H
3			/*
4			note: blackbox equations support the form
5			output[i] = f(input[j] for all j) foreach i
6			which we calculate by calling yhat = f(x),
7			and then residual is y-yhat.
8			*/
9
10			extern int BlackBoxCalcResidual(struct Instance i, double res, struct relation *r);
11
12			/** Compute standard form residual and gradient.
13			See relation_util.h gradient functions
14			for additional notes on the gradient output array and varlist.
15			@param i the relation instance in question.
16			@param residual the residual computed (output).
17			@param gradient the gradient computed (output), an array as long as r->varlist
18			and with elements corresponding to the elements of varlist.
19			@param r the relation data from i.
20			*/
21			extern int BlackBoxCalcResidGrad(struct Instance i, double residual, double gradient, struct relation r);
22
23			/** Compute standard form gradient.
24			See relation_util.h gradient functions
25			for additional notes on the gradient output array and varlist.
26			@param i the relation instance in question.
27			@param gradient the gradient computed (output), an array as long as r->varlist
28			and with elements corresponding to the elements of varlist.
29			@param r the relation data from i.
30			*/
31			extern int BlackBoxCalcGradient(struct Instance i, double gradient, struct relation *r);
32
33			/**
34			Return the output variable instance from r, assuming r is from a blackbox.
35			*/
36			extern struct Instance BlackBoxGetOutputVar(struct relation r);
37
38			/** All the relations evaluated in a single call to y=f(x) have this data in common. */
39			struct BlackBoxCache { /* was extrelcache, sort of. */
40			struct gl_list_t formalArgList; /< only passed on pre_slv /
41			struct BBoxInterp interp; /*< userdata lives in here only /
42			int32 inputsLen; /*< number of actual, not formal, inputs /
43			int32 outputsLen; /*< number of actual, not formal, outputs. /
44			int32 jacobianLen;
45			int32 hessianLen;
46			double inputs; /< aka x; previous input for func eval. /
47			double outputs; /< aka yhat. previous output for func eval. /
48			double inputsJac; /< aka x; previous input for gradient eval. /
49			double jacobian; /< sensitivity dyhat/dx ; row major format; previous gradient output. /
50			double hessian; /< undetermined format /
51			int residCount; /*< number of calls made for y output. /
52			int gradCount; /*< number of calls made for gradient. /
53			int refCount; /* when to destroy */
54			};
55
56			/** All the elements of an array of blackbox relations resulting
57			from a single external statement have the BlackBoxCache in common, but
58			the varlist and lhs are unique to the specific relation.
59			If someone really needs a nodestamp, for some reason,
60			the 'common' pointer is unique to the set.
61			*/
62			struct BlackBoxData {
63			struct BlackBoxCache *common;
64			unsigned long inputArgs; /*< an array of indexes into the varlist;
65			see notes elsewhere about why varlist
66			may be shorter than arglist due to alias/ats.
67			size is in common. */
68			unsigned long lhsindex; /*< location of value yhati in C output array. /
69			unsigned long lhsvar; /*< location of lhs var(yi) in varlist. /
70			};
71
72			/* make a blackboxdata unique to a single relation. */
73			extern struct BlackBoxData CreateBlackBoxData(struct BlackBoxCache common,
74			unsigned long lhsindex,
75			unsigned long lhsVarNumber);
76
77			/* called when destroying the relation containing b. */
78			extern void DestroyBlackBoxData(struct relation * rel, struct BlackBoxData *b);
79
80			/**
81			Returns an initialized common data for a blackbox relation array
82			with an initial refcount 1.
83			Call DeleteRefBlackBoxCache when done with the object, and
84			make a call to AddRef any time the pointer is stored in a
85			persistent structure.
86			@param inputsLen number of actual, not formal, inputs.
87			@param outputsLen number of actual, not formal, outputs.
88			@param formalArgs list of list of args, which will be copied.
89			*/
90			extern struct BlackBoxCache CreateBlackBoxCache( int32 inputsLen, int32 outputsLen, struct gl_list_t formalArgs);
91
92			/** make a persistent reference to b. */
93			extern void AddRefBlackBoxCache(struct BlackBoxCache *b);
94
95			/** remove a persistent reference to *b.
96			sets *b to null before returning.
97			deallocates **b if refcount has dropped to 0.
98			*/
99			extern void DeleteRefBlackBoxCache(struct relation rel, struct BlackBoxCache *b);
100
101
102			#endif /* ASC_REL_BLACKBOX_H */