generic/compiler/exprsym.h

/*
 *  Symbolic Expression Manipulation
 *  by Kirk Abbott
 *  Created: Novermber 21, 1994
 *  Version: $Revision: 1.5 $
 *  Version control file: $RCSfile: exprsym.h,v $
 *  Date last modified: $Date: 1997/07/18 12:29:23 $
 *  Last modified by: $Author: mthomas $
 *
 *  This file is part of the ASCEND compiler.
 *
 *  Copyright (C) 1994,1995 Kirk Andre Abbott.
 *
 *  The Ascend Language Interpreter 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.
 *
 *  The Ascend Language Interpreter is distributed in 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 the program; if not, write to the Free Software Foundation,
 *  Inc., 675 Mass Ave, Cambridge, MA 02139 USA.  Check the file named
 *  COPYING.
 */

/** @file
 *  Symbolic Expression Manipulation
 *  <pre>
 *  When #including .h, make sure these files are #included first:
 *         #utilities/ascConfig.h"
 *         #include "instance_enum.h"
 *  </pre>
 *
 *  The user is reminded that the author of these routines
 *  could not be bothered with dimensionality, so don't expect
 *  much in the way of output that dimensionally checks or
 *  can be converted to real values in non-SI units unless the
 *  input was correct.
 *
 *  The user is also reminded that this code does not deal well
 *  with e_zero. e_zero should not exist in good models in any
 *  case.
 */

#ifndef __EXPRSYM_H_SEEN__
#define __EXPRSYM_H_SEEN__

/**
 * Until we decide whether to let the postfix and
 * infix data structures be shared. we will use these
 * typedefs.
 */
typedef struct Func Func;
typedef struct relation_term Term;
/**< note, so now Term has to be treated like A_TERM. */
typedef struct relation RelationINF;    /**< infix relation */

#define K_TERM(i) ((Term *)(i))
/**< Cast the i back to Term */

extern Term *TermSimplify(Term *term);
/**<
 *  Attempts term simplification. Later different levels of simplification
 *  will be made a feature.
 */

extern Term *Derivative(Term *term, unsigned long wrt,
                        int (*filter)(struct Instance *));
/**<
 *  The low level routine which acutally does the symbolic differentiation
 *  with sub epxression simplification/elimination. In general not a safe
 *  place to start as use is made of a free store which has to be set up
 *  before this funcion may be called.
 */

extern void PrepareDerivatives(int setup, int n_buffers, int buffer_length);
/**<
 *  Call this function before and after doing symbolic derivatives.
 *  If setup is true, a free store of terms will be set up, with the
 *  specified number of buffers and buffer length. I am now using 2
 *  buffers of length 5000.
 *  If set up is false the memory allocated in the previous call to set up
 *  will be deallocated.
 */

#define ShutDownDerivatives() PrepareDerivatives(0,0,0)
/**<
 *  Deallocate memory allocated in the previous call to PrepareDerivatives().
 */

extern Term *TermDerivative(Term *term, unsigned long wrt,
                            int (*filter)(struct Instance *) );
/**<
 *  TermDerivative is the function that is used by RelationDerivative
 *  to generate the derivatives. Again it is perhaps more efficient
 *  to call RelationDerivative.
 */

extern RelationINF *RelDerivative(RelationINF *rel, unsigned long wrt,
                                  int (*filter)(struct Instance *));
/**<
 *  <!--  RelationINF *RelDeriveSloppy(rel,wrt,filter);                -->
 *  <!--  RelationINF *rel;                                            -->
 *  <!--  unsigned long wrt;                                           -->
 *  <!--  int (*filter)(struct Instance *);                            -->
 *  Given a infix relation, a index into its variable list and a function
 *  filter used to classify REAL_ATOM_INSTANCES as variables,parmaters or
 *  constants (or for that matter whatever the user pleases), this function
 *  will return a relation which is the symbolic derivative of the relation,
 *  with respect to the given variable. The relation *belongs* to the caller.
 *  The variale list will be updated to represent the new incidence after
 *  differentiation.
 */

extern void RelDestroySloppy(RelationINF *rel);
/**< 
 *  <!--  void RelDestroySloppy(rel);                                  -->
 *  <!--  RelationINF *rel;                                            -->
 *  This function is to be used to deallocate a relation that was returned
 *  as a result of a call to RelDeriveSloppy.
 *  <pre>
 *  Example usage:
 *      ( .... )
 *      RelationINF *rel,*deriv;
 *      unsigned long wrt = 3;
 *      rel = (...)
 *      PrepareDerivates(1,3,500);
 *      deriv = RelDeriveSloppy(rel,wrt,NULL);
 *      WriteRelationInfix(stderr,deriv);
 *      RelDestroySloppy(deriv);
 *      ShutDownDerivatives();
 *      ( .... )
 *      return;
 *  </pre>
 */

extern RelationINF *RelDeriveSloppy(RelationINF *rel, unsigned long wrt,
                                    int (*filter)(struct Instance *));
/**<
 *  <!--  RelationINF *RelDeriveSloppy(rel,wrt,filter);                -->
 *  <!--  RelationINF *rel;                                            -->
 *  <!--  unsigned long wrt;                                           -->
 *  <!--  int (*filter)(struct Instance *);                            -->
 *  Given a infix relation, a index into its variable list and a function
 *  filter used to classify REAL_ATOM_INSTANCES as variables,parmaters or
 *  constants (or for that matter whatever the user pleases), this function
 *  will return a relation which is the symbolic derivative of the relation,
 *  with respect to the given variable.<br><br>
 *
 *  NOTE 1:<br>
 *  This function is provided for the benefit of users, who would like
 *  access to symbolic derivatives of a TRANSIENT nature. By this
 *  I mean that the derivative is going to be evaluated, written out etc,
 *  and then discarded. It makes certain shortcuts in the interest of speed
 *  For example, the returned variable list does not relect the fact
 *  that incidence may have been lost due to the process of doing the
 *  derivatives; but is still a valid list as differentiation can reduce
 *  incidence but not increase it.<br><br>
 *
 *  NOTE 2:<br>
 *  The relation structure that is returned *belongs* to the user.
 *  The variable list associated with the relation *belongs* to the user.
 *  The terms that make up the relation *do not belong* to the user.
 *  In fact *DO NOT deallocate any of these structures yourself. Use the
 *  above function RelDestroySloppy. This will deallocate the necessary
 *  structures. The term lists are the property of the freestore that was
 *  set up in PrepareDerivatives and will be handled by that store on
 *  Shutdown.
 */

#endif /* __EXPRSYM_H_SEEN__ */

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