/[ascend]/trunk/base/generic/compiler/exprsym.h
ViewVC logotype

Contents of /trunk/base/generic/compiler/exprsym.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 54 - (show annotations) (download) (as text)
Tue Aug 2 11:20:09 2005 UTC (14 years, 4 months ago) by jds
File MIME type: text/x-chdr
File size: 7143 byte(s)
Manual rework of doxygen comments in all headers.
- Added @file comment to all headers.
- Added parameter names to all function declarations in headers.
- Corrected comment referencing where necessary.
- Split some comments which documented blocks of declarations.
- Converted notes about required work into @todo comments so doxygen can generate a todo list.
Minor bug fixes.
1 /*
2 * Symbolic Expression Manipulation
3 * by Kirk Abbott
4 * Created: Novermber 21, 1994
5 * Version: $Revision: 1.5 $
6 * Version control file: $RCSfile: exprsym.h,v $
7 * Date last modified: $Date: 1997/07/18 12:29:23 $
8 * Last modified by: $Author: mthomas $
9 *
10 * This file is part of the ASCEND compiler.
11 *
12 * Copyright (C) 1994,1995 Kirk Andre Abbott.
13 *
14 * The Ascend Language Interpreter is free software; you can redistribute
15 * it and/or modify it under the terms of the GNU General Public License as
16 * published by the Free Software Foundation; either version 2 of the
17 * License, or (at your option) any later version.
18 *
19 * The Ascend Language Interpreter is distributed in hope that it will be
20 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22 * General Public License for more details.
23 *
24 * You should have received a copy of the GNU General Public License
25 * along with the program; if not, write to the Free Software Foundation,
26 * Inc., 675 Mass Ave, Cambridge, MA 02139 USA. Check the file named
27 * COPYING.
28 */
29
30 /** @file
31 * Symbolic Expression Manipulation
32 * <pre>
33 * When #including .h, make sure these files are #included first:
34 * #utilities/ascConfig.h"
35 * #include "instance_enum.h"
36 * </pre>
37 *
38 * The user is reminded that the author of these routines
39 * could not be bothered with dimensionality, so don't expect
40 * much in the way of output that dimensionally checks or
41 * can be converted to real values in non-SI units unless the
42 * input was correct.
43 *
44 * The user is also reminded that this code does not deal well
45 * with e_zero. e_zero should not exist in good models in any
46 * case.
47 */
48
49 #ifndef __EXPRSYM_H_SEEN__
50 #define __EXPRSYM_H_SEEN__
51
52 /**
53 * Until we decide whether to let the postfix and
54 * infix data structures be shared. we will use these
55 * typedefs.
56 */
57 typedef struct Func Func;
58 typedef struct relation_term Term;
59 /**< note, so now Term has to be treated like A_TERM. */
60 typedef struct relation RelationINF; /**< infix relation */
61
62 #define K_TERM(i) ((Term *)(i))
63 /**< Cast the i back to Term */
64
65 extern Term *TermSimplify(Term *term);
66 /**<
67 * Attempts term simplification. Later different levels of simplification
68 * will be made a feature.
69 */
70
71 extern Term *Derivative(Term *term, unsigned long wrt,
72 int (*filter)(struct Instance *));
73 /**<
74 * The low level routine which acutally does the symbolic differentiation
75 * with sub epxression simplification/elimination. In general not a safe
76 * place to start as use is made of a free store which has to be set up
77 * before this funcion may be called.
78 */
79
80 extern void PrepareDerivatives(int setup, int n_buffers, int buffer_length);
81 /**<
82 * Call this function before and after doing symbolic derivatives.
83 * If setup is true, a free store of terms will be set up, with the
84 * specified number of buffers and buffer length. I am now using 2
85 * buffers of length 5000.
86 * If set up is false the memory allocated in the previous call to set up
87 * will be deallocated.
88 */
89
90 #define ShutDownDerivatives() PrepareDerivatives(0,0,0)
91 /**<
92 * Deallocate memory allocated in the previous call to PrepareDerivatives().
93 */
94
95 extern Term *TermDerivative(Term *term, unsigned long wrt,
96 int (*filter)(struct Instance *) );
97 /**<
98 * TermDerivative is the function that is used by RelationDerivative
99 * to generate the derivatives. Again it is perhaps more efficient
100 * to call RelationDerivative.
101 */
102
103 extern RelationINF *RelDerivative(RelationINF *rel, unsigned long wrt,
104 int (*filter)(struct Instance *));
105 /**<
106 * <!-- RelationINF *RelDeriveSloppy(rel,wrt,filter); -->
107 * <!-- RelationINF *rel; -->
108 * <!-- unsigned long wrt; -->
109 * <!-- int (*filter)(struct Instance *); -->
110 * Given a infix relation, a index into its variable list and a function
111 * filter used to classify REAL_ATOM_INSTANCES as variables,parmaters or
112 * constants (or for that matter whatever the user pleases), this function
113 * will return a relation which is the symbolic derivative of the relation,
114 * with respect to the given variable. The relation *belongs* to the caller.
115 * The variale list will be updated to represent the new incidence after
116 * differentiation.
117 */
118
119 extern void RelDestroySloppy(RelationINF *rel);
120 /**<
121 * <!-- void RelDestroySloppy(rel); -->
122 * <!-- RelationINF *rel; -->
123 * This function is to be used to deallocate a relation that was returned
124 * as a result of a call to RelDeriveSloppy.
125 * <pre>
126 * Example usage:
127 * ( .... )
128 * RelationINF *rel,*deriv;
129 * unsigned long wrt = 3;
130 * rel = (...)
131 * PrepareDerivates(1,3,500);
132 * deriv = RelDeriveSloppy(rel,wrt,NULL);
133 * WriteRelationInfix(stderr,deriv);
134 * RelDestroySloppy(deriv);
135 * ShutDownDerivatives();
136 * ( .... )
137 * return;
138 * </pre>
139 */
140
141 extern RelationINF *RelDeriveSloppy(RelationINF *rel, unsigned long wrt,
142 int (*filter)(struct Instance *));
143 /**<
144 * <!-- RelationINF *RelDeriveSloppy(rel,wrt,filter); -->
145 * <!-- RelationINF *rel; -->
146 * <!-- unsigned long wrt; -->
147 * <!-- int (*filter)(struct Instance *); -->
148 * Given a infix relation, a index into its variable list and a function
149 * filter used to classify REAL_ATOM_INSTANCES as variables,parmaters or
150 * constants (or for that matter whatever the user pleases), this function
151 * will return a relation which is the symbolic derivative of the relation,
152 * with respect to the given variable.<br><br>
153 *
154 * NOTE 1:<br>
155 * This function is provided for the benefit of users, who would like
156 * access to symbolic derivatives of a TRANSIENT nature. By this
157 * I mean that the derivative is going to be evaluated, written out etc,
158 * and then discarded. It makes certain shortcuts in the interest of speed
159 * For example, the returned variable list does not relect the fact
160 * that incidence may have been lost due to the process of doing the
161 * derivatives; but is still a valid list as differentiation can reduce
162 * incidence but not increase it.<br><br>
163 *
164 * NOTE 2:<br>
165 * The relation structure that is returned *belongs* to the user.
166 * The variable list associated with the relation *belongs* to the user.
167 * The terms that make up the relation *do not belong* to the user.
168 * In fact *DO NOT deallocate any of these structures yourself. Use the
169 * above function RelDestroySloppy. This will deallocate the necessary
170 * structures. The term lists are the property of the freestore that was
171 * set up in PrepareDerivatives and will be handled by that store on
172 * Shutdown.
173 */
174
175 #endif /* __EXPRSYM_H_SEEN__ */
176

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22