generic/compiler/exprsym.h

/*  ASCEND modelling environment
    Copyright (C) 1994,1995 Kirk Andre Abbott.
    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, 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
    Symbolic Expression Manipulation
    
    Requires:
    #utilities/ascConfig.h"
    #include "instance_enum.h"

    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.

    This code does not deal well with e_zero. e_zero should not exist in good 
    models in any case.
*//*
 *  by Kirk Abbott
 *  Created: Novermber 21, 1994
 *  Last in CVS: $Revision: 1.5 $ $Date: 1997/07/18 12:29:23 $ $Author: mthomas $
*/


#ifndef ASC_EXPRSYM_H
#define ASC_EXPRSYM_H

/** addtogroup compiler Compiler
    @{
*/

/**
 * 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 actually 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 *));
/**<
 *  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);
/**< 
 *  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 *));
/**<
 *  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 /* ASC_EXPRSYM_H */

1	/* ASCEND modelling environment
2	Copyright (C) 1994,1995 Kirk Andre Abbott.
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, 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	//*
20	@file
21	Symbolic Expression Manipulation
22
23	Requires:
24	#utilities/ascConfig.h"
25	#include "instance_enum.h"
26
27	The author of these routines could not be bothered with dimensionality, so
28	don't expect much in the way of output that dimensionally checks or can be
29	converted to real values in non-SI units unless the input was correct.
30
31	This code does not deal well with e_zero. e_zero should not exist in good
32	models in any case.
33	//
34	* by Kirk Abbott
35	* Created: Novermber 21, 1994
36	* Last in CVS: $Revision: 1.5 $ $Date: 1997/07/18 12:29:23 $ $Author: mthomas $
37	*/
38
39
40	#ifndef ASC_EXPRSYM_H
41	#define ASC_EXPRSYM_H
42
43	/** addtogroup compiler Compiler
44	@{
45	*/
46
47	/**
48	* Until we decide whether to let the postfix and
49	* infix data structures be shared. we will use these
50	* typedefs.
51	*/
52	typedef struct Func Func;
53
54	typedef struct relation_term Term;
55	/*< note, so now Term has to be treated like A_TERM. /
56
57	typedef struct relation RelationINF; /*< infix relation /
58
59	#define K_TERM(i) ((Term *)(i))
60	/*< Cast the i back to Term /
61
62	extern Term TermSimplify(Term term);
63	/**<
64	* Attempts term simplification. Later different levels of simplification
65	* will be made a feature.
66	*/
67
68	extern Term Derivative(Term term, unsigned long wrt,
69	int (filter)(struct Instance ));
70	/**<
71	* The low level routine which actually does the symbolic differentiation
72	* with sub epxression simplification/elimination. In general not a safe
73	* place to start as use is made of a free store which has to be set up
74	* before this funcion may be called.
75	*/
76
77	extern void PrepareDerivatives(int setup, int n_buffers, int buffer_length);
78	/**<
79	* Call this function before and after doing symbolic derivatives.
80	* If setup is true, a free store of terms will be set up, with the
81	* specified number of buffers and buffer length. I am now using 2
82	* buffers of length 5000.
83	* If set up is false the memory allocated in the previous call to set up
84	* will be deallocated.
85	*/
86
87	#define ShutDownDerivatives() PrepareDerivatives(0,0,0)
88	/**<
89	* Deallocate memory allocated in the previous call to PrepareDerivatives().
90	*/
91
92	extern Term TermDerivative(Term term, unsigned long wrt,
93	int (filter)(struct Instance ) );
94	/**<
95	* TermDerivative is the function that is used by RelationDerivative
96	* to generate the derivatives. Again it is perhaps more efficient
97	* to call RelationDerivative.
98	*/
99
100	extern RelationINF RelDerivative(RelationINF rel, unsigned long wrt,
101	int (filter)(struct Instance ));
102	/**<
103	* Given a infix relation, a index into its variable list and a function
104	* filter used to classify REAL_ATOM_INSTANCES as variables,parmaters or
105	* constants (or for that matter whatever the user pleases), this function
106	* will return a relation which is the symbolic derivative of the relation,
107	* with respect to the given variable. The relation belongs to the caller.
108	* The variale list will be updated to represent the new incidence after
109	* differentiation.
110	*/
111
112	extern void RelDestroySloppy(RelationINF *rel);
113	/**<
114	* This function is to be used to deallocate a relation that was returned
115	* as a result of a call to RelDeriveSloppy.
116	* <pre>
117	* Example usage:
118	* ( .... )
119	* RelationINF rel,deriv;
120	* unsigned long wrt = 3;
121	* rel = (...)
122	* PrepareDerivates(1,3,500);
123	* deriv = RelDeriveSloppy(rel,wrt,NULL);
124	* WriteRelationInfix(stderr,deriv);
125	* RelDestroySloppy(deriv);
126	* ShutDownDerivatives();
127	* ( .... )
128	* return;
129	* </pre>
130	*/
131
132	extern RelationINF RelDeriveSloppy(RelationINF rel, unsigned long wrt,
133	int (filter)(struct Instance ));
134	/**<
135	* Given a infix relation, a index into its variable list and a function
136	* filter used to classify REAL_ATOM_INSTANCES as variables,parmaters or
137	* constants (or for that matter whatever the user pleases), this function
138	* will return a relation which is the symbolic derivative of the relation,
139	* with respect to the given variable.<br><br>
140	*
141	* NOTE 1:<br>
142	* This function is provided for the benefit of users, who would like
143	* access to symbolic derivatives of a TRANSIENT nature. By this
144	* I mean that the derivative is going to be evaluated, written out etc,
145	* and then discarded. It makes certain shortcuts in the interest of speed
146	* For example, the returned variable list does not relect the fact
147	* that incidence may have been lost due to the process of doing the
148	* derivatives; but is still a valid list as differentiation can reduce
149	* incidence but not increase it.<br><br>
150	*
151	* NOTE 2:<br>
152	* The relation structure that is returned belongs to the user.
153	* The variable list associated with the relation belongs to the user.
154	* The terms that make up the relation do not belong to the user.
155	* In fact *DO NOT deallocate any of these structures yourself. Use the
156	* above function RelDestroySloppy. This will deallocate the necessary
157	* structures. The term lists are the property of the freestore that was
158	* set up in PrepareDerivatives and will be handled by that store on
159	* Shutdown.
160	*/
161
162	/* @} */
163
164	#endif /* ASC_EXPRSYM_H */
165