ascend/compiler/bintoken.h

/*  ASCEND modelling environment
    Copyright (C) 2006-2011 Carnegie Mellon University
    Copyright (C) 1998 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, 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., 59 Temple Place - Suite 330,
    Boston, MA 02111-1307, USA.
*//** @file
    Binary tokens implementation for real relation instances.
    
    Note that this header and btprolog.h are a pair.
    btprolog exists to make the C compiler job simpler -
    we don't want it to know about struct Instance when
    building code because we may not have the compiler
    directory available. btprolog.h is installed with
    the ascend binaries or scripts.
*//*
    By Benjamin A. Allan
    Jan 7, 1998.
    Last in CVS: $Revision: 1.2 $ $Date: 1998/06/16 16:38:37 $ $Author: mthomas $
*/

#ifndef ASC_BINTOKEN_H
#define ASC_BINTOKEN_H

#include <ascend/general/platform.h>
#include "instance_enum.h"
#include "compiler.h"

/** @addtogroup compiler_bintok Compiler Binary Tokens
    @{
*/

enum bintoken_kind {
  BT_error,
  BT_C,
  BT_F77 /**< ansi f77, unimplemented */
};

/**
 * Set the configurations for building code.
 * This function must be called before Create is.<br><br>
 *
 * srcname, objname, libname, buildcommand, unlinkcommand
 * are all OS/compiler specific.
 * maxreln is the largest number of relations to be allowed in a
 * single generated C file.
 * verbose, if nonzero, causes human-edible comments in generated
 * code. housekeep, if given, will cause limited OS housekeeping
 * of unneeded files; specifically $srcname, objname will be deleted
 * after a successful link.
 */
ASC_DLLSPEC int BinTokenSetOptions(
    CONST char *srcname, CONST char *objname, CONST char *libname
    ,CONST char *buildcommand, CONST char *unlinkcommand
    ,unsigned long maxreln
    ,int verbose, int housekeep
);

/**
 * Frees global data allocated during loading.
 * Do not call any previously loaded functions after this is
 * executed. Generally, this should only be called at shutdown.
 */
ASC_DLLSPEC void BinTokenClearTables(void);

/**
 * When all the references expire, we might unload the library.
 * Note there is no AddReference since all the references
 * are made 1 per share at load time.
 * This should be called each time a share that references
 * btable is destroyed, not each time a relation is destroyed.
 */
extern void BinTokenDeleteReference(int btable);

/**
 * Searches for unbinary equations in the tree of root and
 * compiles them to source, then object, then dynamically loaded
 * library. Then associates the compiled code to the equations.
 * The language and compiler tools are determined from method.
 */
ASC_DLLSPEC void BinTokensCreate(struct Instance *root, enum bintoken_kind method);

/**
 * Calculates residual of relation indicated by btable and bindex
 * using the data in vars and putting the result in residual.
 * Vars is assumed already filled with values.
 * This function is SIGFPE safe.
 * Returns an error code (0 if ok, 1 if couldn't evaluate function).
 * May be safely called on token relation instances only.
 */
ASC_DLLSPEC int BinTokenCalcResidual(int btable, int bindex, double *vars, double *residual);

/**
 * Calculates gradient of relation indicated by btable and bindex
 * using the data in vars and putting the result in gradient.
 * Returns nonzero if can't evaluate gradient using binary
 * form of token relation.
 * Vars is assumed already filled with values.
 * Residual is free anyway, so we calculate it, too.
 * May be safely called on token relation instances only.
 */
extern int BinTokenCalcGradient(int btable, int bindex, double *vars,
                                double *residual, double *gradient);

/* @} */

#endif  /* ASC_BINTOKEN_H */

1	johnpye	1046	/* ASCEND modelling environment
2	jpye	2388	Copyright (C) 2006-2011 Carnegie Mellon University
3	johnpye	1046	Copyright (C) 1998 Carnegie Mellon University
4	aw0a	1
5	johnpye	1046	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, or (at your option)
8			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., 59 Temple Place - Suite 330,
18			Boston, MA 02111-1307, USA.
19			//* @file
20	jpye	2388	Binary tokens implementation for real relation instances.
21
22			Note that this header and btprolog.h are a pair.
23			btprolog exists to make the C compiler job simpler -
24			we don't want it to know about struct Instance when
25			building code because we may not have the compiler
26			directory available. btprolog.h is installed with
27			the ascend binaries or scripts.
28	johnpye	1046	//
29			By Benjamin A. Allan
30			Jan 7, 1998.
31			Last in CVS: $Revision: 1.2 $ $Date: 1998/06/16 16:38:37 $ $Author: mthomas $
32			*/
33	jds	54
34	johnpye	162	#ifndef ASC_BINTOKEN_H
35			#define ASC_BINTOKEN_H
36	aw0a	1
37	jpye	2323	#include <ascend/general/platform.h>
38	jpye	1684	#include "instance_enum.h"
39	johnpye	1210	#include "compiler.h"
40
41	jpye	2316	/** @addtogroup compiler_bintok Compiler Binary Tokens
42	johnpye	1066	@{
43			*/
44
45	aw0a	1	enum bintoken_kind {
46			BT_error,
47			BT_C,
48	johnpye	1046	BT_F77 /*< ansi f77, unimplemented /
49	aw0a	1	};
50
51	johnpye	506	/**
52	aw0a	1	* Set the configurations for building code.
53	jds	54	* This function must be called before Create is.<br><br>
54	aw0a	1	*
55			* srcname, objname, libname, buildcommand, unlinkcommand
56			* are all OS/compiler specific.
57			* maxreln is the largest number of relations to be allowed in a
58			* single generated C file.
59			* verbose, if nonzero, causes human-edible comments in generated
60			* code. housekeep, if given, will cause limited OS housekeeping
61			* of unneeded files; specifically $srcname, objname will be deleted
62			* after a successful link.
63			*/
64	johnpye	1063	ASC_DLLSPEC int BinTokenSetOptions(
65	johnpye	1046	CONST char srcname, CONST char objname, CONST char *libname
66			,CONST char buildcommand, CONST char unlinkcommand
67			,unsigned long maxreln
68			,int verbose, int housekeep
69			);
70	aw0a	1
71	jds	54	/**
72	aw0a	1	* Frees global data allocated during loading.
73			* Do not call any previously loaded functions after this is
74			* executed. Generally, this should only be called at shutdown.
75			*/
76	jpye	2388	ASC_DLLSPEC void BinTokenClearTables(void);
77	aw0a	1
78	jds	54	/**
79	aw0a	1	* When all the references expire, we might unload the library.
80			* Note there is no AddReference since all the references
81			* are made 1 per share at load time.
82			* This should be called each time a share that references
83			* btable is destroyed, not each time a relation is destroyed.
84			*/
85	jds	54	extern void BinTokenDeleteReference(int btable);
86	aw0a	1
87	jds	54	/**
88	aw0a	1	* Searches for unbinary equations in the tree of root and
89			* compiles them to source, then object, then dynamically loaded
90			* library. Then associates the compiled code to the equations.
91			* The language and compiler tools are determined from method.
92			*/
93	jpye	2388	ASC_DLLSPEC void BinTokensCreate(struct Instance *root, enum bintoken_kind method);
94	aw0a	1
95	jds	54	/**
96	aw0a	1	* Calculates residual of relation indicated by btable and bindex
97			* using the data in vars and putting the result in residual.
98	jds	54	* Vars is assumed already filled with values.
99	aw0a	1	* This function is SIGFPE safe.
100	jds	54	* Returns an error code (0 if ok, 1 if couldn't evaluate function).
101	aw0a	1	* May be safely called on token relation instances only.
102			*/
103	jpye	2388	ASC_DLLSPEC int BinTokenCalcResidual(int btable, int bindex, double vars, double residual);
104	aw0a	1
105	jds	54	/**
106			* Calculates gradient of relation indicated by btable and bindex
107			* using the data in vars and putting the result in gradient.
108	aw0a	1	* Returns nonzero if can't evaluate gradient using binary
109			* form of token relation.
110			* Vars is assumed already filled with values.
111	jds	54	* Residual is free anyway, so we calculate it, too.
112	aw0a	1	* May be safely called on token relation instances only.
113			*/
114	jds	54	extern int BinTokenCalcGradient(int btable, int bindex, double *vars,
115			double residual, double gradient);
116
117	johnpye	1066	/* @} */
118
119	johnpye	162	#endif /* ASC_BINTOKEN_H */
120	jds	54