generic/compiler/rel_blackbox.h

/*
    ASCEND Language Interpreter
    Copyright (C) 2006 Carnegie-Mellon University

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
    This file is part of the SLV solver.
*//** @file

    @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).
*/

#ifndef ASC_REL_BLACKBOX_H
#define ASC_REL_BLACKBOX_H

/** addtogroup compiler Compiler
    @{
*/

#include <utilities/ascConfig.h>
#include "instance_enum.h"
#include "relation_type.h"
#include <general/list.h>
#include "expr_types.h"
#include "extfunc.h"

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(CONST 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 *argListNames; /**< list of list of names. */
    struct Name *dataName; /**< name of the DATA instance. */
    struct ExternalFunc *efunc; /**< external function table. */
    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 */
    int count; /**< serial number */
};

/** Fetch the input array len size. 
    @param bbc the source.
*/
extern int32 BlackBoxCacheInputsLen(struct BlackBoxCache *bbc);

/** 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;
    int count;
};

/** make a blackboxdata unique to a single relation.
@param common the data common to all the relations in the array of blackbox output relations.
@param lhsindex the index of this relation's residual in the blackbox output vector.
@param lhsVarNumber the index of the output variable (y) in the relation's varlist. 
*/
extern struct BlackBoxData *CreateBlackBoxData(struct BlackBoxCache *common);

/* do anoncopy of bbox data for relation sharing. */
extern void CopyBlackBoxDataByReference(struct relation *src, struct relation *dest, void *bboxtable_p);

/* 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 argListNames list of lists of names of real atom instances in/output.
 @param dataName name of the data instance.
*/
extern struct BlackBoxCache *CreateBlackBoxCache( int32 inputsLen, int32 outputsLen, struct gl_list_t *argListNames, struct Name *dataName, struct ExternalFunc *efunc);

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

/** dispatch the init function on a bbox after updating the input instance list
  from the names list.
  @param context the parent model containing the relations the cache is
   referenced by.
  @param b a cache in need of the init call.
 */
extern void InitBBox(struct Instance *context, 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	909	/*
2			ASCEND Language Interpreter
3			Copyright (C) 2006 Carnegie-Mellon University
4
5			This program is free software; you can redistribute it and/or modify
6			it under the terms of the GNU General Public License as published by
7			the Free Software Foundation; either version 2 of the License, or
8			(at your option) any later version.
9
10			This program is distributed in the hope that it will be useful,
11			but WITHOUT ANY WARRANTY; without even the implied warranty of
12			MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13			GNU General Public License for more details.
14
15			You should have received a copy of the GNU General Public License
16			along with this program; if not, write to the Free Software
17			Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
18			This file is part of the SLV solver.
19			//* @file
20
21			@NOTE blackbox equations support the form
22
23			output[i] = f(input[j] for all j) foreach i
24
25	johnpye	908	which we calculate by calling yhat = f(x),
26	johnpye	909	and then residual is (y - yhat).
27	johnpye	908	*/
28
29	johnpye	909	#ifndef ASC_REL_BLACKBOX_H
30			#define ASC_REL_BLACKBOX_H
31
32	johnpye	1066	/** addtogroup compiler Compiler
33			@{
34			*/
35
36	johnpye	1039	#include <utilities/ascConfig.h>
37			#include "instance_enum.h"
38			#include "relation_type.h"
39			#include <general/list.h>
40			#include "expr_types.h"
41			#include "extfunc.h"
42
43	johnpye	908	extern int BlackBoxCalcResidual(struct Instance i, double res, struct relation *r);
44
45			/** Compute standard form residual and gradient.
46			See relation_util.h gradient functions
47			for additional notes on the gradient output array and varlist.
48			@param i the relation instance in question.
49			@param residual the residual computed (output).
50			@param gradient the gradient computed (output), an array as long as r->varlist
51			and with elements corresponding to the elements of varlist.
52			@param r the relation data from i.
53			*/
54			extern int BlackBoxCalcResidGrad(struct Instance i, double residual, double gradient, struct relation r);
55
56			/** Compute standard form gradient.
57			See relation_util.h gradient functions
58			for additional notes on the gradient output array and varlist.
59			@param i the relation instance in question.
60			@param gradient the gradient computed (output), an array as long as r->varlist
61			and with elements corresponding to the elements of varlist.
62			@param r the relation data from i.
63			*/
64			extern int BlackBoxCalcGradient(struct Instance i, double gradient, struct relation *r);
65
66			/**
67			Return the output variable instance from r, assuming r is from a blackbox.
68			*/
69	johnpye	1031	extern struct Instance BlackBoxGetOutputVar(CONST struct relation r);
70	johnpye	908
71			/** All the relations evaluated in a single call to y=f(x) have this data in common. */
72			struct BlackBoxCache { /* was extrelcache, sort of. */
73	johnpye	1031	struct gl_list_t argListNames; /< list of list of names. /
74			struct Name dataName; /< name of the DATA instance. /
75			struct ExternalFunc efunc; /< external function table. /
76	johnpye	908	struct BBoxInterp interp; /*< userdata lives in here only /
77			int32 inputsLen; /*< number of actual, not formal, inputs /
78			int32 outputsLen; /*< number of actual, not formal, outputs. /
79			int32 jacobianLen;
80			int32 hessianLen;
81			double inputs; /< aka x; previous input for func eval. /
82			double outputs; /< aka yhat. previous output for func eval. /
83			double inputsJac; /< aka x; previous input for gradient eval. /
84			double jacobian; /< sensitivity dyhat/dx ; row major format; previous gradient output. /
85			double hessian; /< undetermined format /
86			int residCount; /*< number of calls made for y output. /
87			int gradCount; /*< number of calls made for gradient. /
88	johnpye	1031	int refCount; /*< when to destroy /
89			int count; /*< serial number /
90	johnpye	908	};
91
92	johnpye	1031	/** Fetch the input array len size.
93			@param bbc the source.
94			*/
95			extern int32 BlackBoxCacheInputsLen(struct BlackBoxCache *bbc);
96
97	johnpye	908	/** All the elements of an array of blackbox relations resulting
98			from a single external statement have the BlackBoxCache in common, but
99			the varlist and lhs are unique to the specific relation.
100			If someone really needs a nodestamp, for some reason,
101			the 'common' pointer is unique to the set.
102			*/
103			struct BlackBoxData {
104			struct BlackBoxCache *common;
105	johnpye	1031	int count;
106	johnpye	908	};
107
108	johnpye	1031	/** make a blackboxdata unique to a single relation.
109			@param common the data common to all the relations in the array of blackbox output relations.
110			@param lhsindex the index of this relation's residual in the blackbox output vector.
111			@param lhsVarNumber the index of the output variable (y) in the relation's varlist.
112			*/
113			extern struct BlackBoxData CreateBlackBoxData(struct BlackBoxCache common);
114	johnpye	908
115	johnpye	1031	/* do anoncopy of bbox data for relation sharing. */
116			extern void CopyBlackBoxDataByReference(struct relation src, struct relation dest, void *bboxtable_p);
117
118	johnpye	908	/* called when destroying the relation containing b. */
119			extern void DestroyBlackBoxData(struct relation * rel, struct BlackBoxData *b);
120
121			/**
122			Returns an initialized common data for a blackbox relation array
123			with an initial refcount 1.
124			Call DeleteRefBlackBoxCache when done with the object, and
125			make a call to AddRef any time the pointer is stored in a
126			persistent structure.
127			@param inputsLen number of actual, not formal, inputs.
128			@param outputsLen number of actual, not formal, outputs.
129	johnpye	1031	@param argListNames list of lists of names of real atom instances in/output.
130			@param dataName name of the data instance.
131	johnpye	908	*/
132	johnpye	1031	extern struct BlackBoxCache CreateBlackBoxCache( int32 inputsLen, int32 outputsLen, struct gl_list_t argListNames, struct Name dataName, struct ExternalFunc efunc);
133	johnpye	908
134			/** make a persistent reference to b. */
135			extern void AddRefBlackBoxCache(struct BlackBoxCache *b);
136
137	johnpye	1031	/** dispatch the init function on a bbox after updating the input instance list
138			from the names list.
139			@param context the parent model containing the relations the cache is
140			referenced by.
141			@param b a cache in need of the init call.
142			*/
143			extern void InitBBox(struct Instance context, struct BlackBoxCache b);
144
145	johnpye	908	/** remove a persistent reference to *b.
146			sets *b to null before returning.
147			deallocates **b if refcount has dropped to 0.
148			*/
149			extern void DeleteRefBlackBoxCache(struct relation rel, struct BlackBoxCache *b);
150
151	johnpye	1066	/* @} */
152
153	johnpye	908	#endif /* ASC_REL_BLACKBOX_H */