generic/compiler/mathinst.h

/*  ASCEND modelling environment
    Copyright (C) 2006 Carnegie Mellon University
    Copyright (C) 1990, 1993, 1994 Thomas Guthrie Epperly

    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
    Ascend Instance Math Object Functions.
    
    Relation, logical relation, and When querying and assignment routines

    Requires:
    #include "utilities/ascConfig.h"
    #include "fractions.h"
    #include "instance_enum.h"
    #include "compiler.h"
    #include "dimen.h"
    #include "expr_types.h"
*//*
    by Tom Epperly
    8/16/89
    Last in CVS: $Revision: 1.8 $ $Date: 1998/05/06 17:33:37 $ $Author: ballan $
*/

#ifndef ASC_MATHINST_H
#define ASC_MATHINST_H

/** addtogroup compiler Compiler
    @{
*/

ASC_DLLSPEC enum Expr_enum GetInstanceRelationType(CONST struct Instance *i);
/**<
    This returns the type of the relation associated with this relations
    instance (REL_INST).
    This should be one of e_token, e_opcode, e_glassbox or e_blackbox.
*/

ASC_DLLSPEC CONST struct relation *GetInstanceRelationOnly(CONST struct Instance *i);
/**<
    This returns the guts of a relation instance (REL_INST).
    These should be treated as read only usually because you don't
    know who is sharing those guts.
*/

ASC_DLLSPEC CONST struct relation *GetInstanceRelation(CONST struct Instance *i,
                                                  enum Expr_enum *type);
/**<
    This returns the value of a relation inst(REL_INST). It will fill in
    the type of the relation associated with this relation instance.
    This will be one of e_token, e_opcode, e_glassbox or e_blackbox,
    or possibly e_undefined.

    @TODO Important! This appears not to be to inverse of the rel_instance
    function in the solver! Why is that? -- JP
*/

extern struct relation *GetInstanceRelToModify(struct Instance *i,
                                               enum Expr_enum *type);
/**<
    This returns the value of a relation inst(REL_INST). In this function
    we do not get a CONST structure and therefore we can modify it. This
    is useful while marking conditional relations.
*/

extern void SetInstanceRelation(struct Instance *i,
                                         struct relation *rel,
                                         enum Expr_enum type);
/**< 
    Set the relation to rel.  rel will be incorporated into the instance,
    so rel should not be modified or destroyed. The type of the relation
    *has* to be provided.

    rel and type may be the NULL/e_undefined combination.
*/

ASC_DLLSPEC CONST struct logrelation *GetInstanceLogRelOnly(CONST struct Instance*i);
/**< 
    This returns the guts of a logical relation instance (LREL_INST).
    These should be treated as read only usually because you don't
    know who is sharing those guts.
*/

ASC_DLLSPEC CONST struct logrelation *GetInstanceLogRel(CONST struct Instance *i);
/**< 
    This returns the value of a logrelation inst(LREL_INST).
*/

extern struct logrelation *GetInstanceLogRelToModify(struct Instance *i);
/**< 
    This returns the value of a logrelation inst(LREL_INST). In this function
    we do not get a CONST structure and therefore we can modify it. This
    is useful while marking conditional logrelations.
*/

extern void SetInstanceLogRel(struct Instance *i, struct logrelation *lrel);
/**< 
    Set the logical relation to lrel.  rel will be incorporated into the
    instance, so rel should not be modified or destroyed.
*/

ASC_DLLSPEC struct gl_list_t *GetInstanceOperands(CONST struct Instance *i);
/**< 
    Returns list of vars/models/equations in a mathematical relationship.
    Accepts all instance kinds. returns list only if the query makes
    sense, but list may be empty. List is yours to destroy, but its
    contents are not.
*/

extern struct gl_list_t *GetInstanceWhenVars(CONST struct Instance *i);
/**< 
    This returns the list of variables associated with this when
    instance (WHEN_INST)
*/

extern struct gl_list_t *GetInstanceWhenCases(CONST struct Instance *i);
/**< 
    This returns the list of cases associated with this when
    instance (WHEN_INST)
*/

extern struct gl_list_t *GetInstanceWhens(CONST struct Instance *i);
/**< 
    This returns the list of whens associated with this instance.
    Instance can be a model, relation,when,boolean, integer or symbol.
*/

extern void SetWhenVarList(struct Instance *i, struct gl_list_t *whenvars);
/**< 
    Set the list of variables of a when instance to whenvars
*/

extern void SetWhenCases(struct Instance *i, struct gl_list_t *whencases);
/**< 
    Set the list of cases of a when instance to whencases
*/

/*------------------------------------------------------------------------------
    SPECIAL REAL ATOM FUNCTIONS
    
    Each real instance knows what mathematical relations that it appears in.
    That information can be acessed by the following routines.
    Same for discrete variables.
*/

ASC_DLLSPEC unsigned long RelationsCount(CONST struct Instance *i);
/**< 
    This will return the number of relations that instance "i" appears in.
    "i" must be a REAL_ATOM_INST.  Otherwise, this routine will
    bomb.
*/

ASC_DLLSPEC struct Instance *RelationsForAtom(CONST struct Instance *i,
                                         unsigned long c);
/**<
    This routine will return the c'th relation in instance i's relation list.
    "i" must be a REAL_ATOM_INST and 0 < c <= RelationsCount(i).
*/

extern void AddRelation(struct Instance *i, struct Instance *reln);
/**< 
    Add the relation instance reln to instance i's relation list.  "i" must
    be of type REAL_ATOM_INST and reln must be of type REL_INST.
*/

extern void RemoveRelation(struct Instance *i, struct Instance *reln);
/**< 
    Remove reln from i's relation list.  If 'reln' isn't found in i's relation
    list, execution continues with a warning message.
*/

ASC_DLLSPEC unsigned long LogRelationsCount(CONST struct Instance *i);
/**< 
    This will return the number of logical relations that instance "i"
    appears in. "i" must be a BOOLEAN_ATOM_INST, REL_INST or LREL_INST
*/

ASC_DLLSPEC struct Instance *LogRelationsForInstance(CONST struct Instance *i,
                                                unsigned long c);
/**<
    This routine will return the c'th logical relation in instance i's
    logical relation list. "i" must be  BOOLEAN_ATOM_INST, REL_INST or
    LREL_INST  and  0 < c <= LogRelationsCount(i).
*/

extern void AddLogRel(struct Instance *i, struct Instance *reln);
/**< 
    Add the logical relation instance lreln to instance i's logical relation
    list.  "i" must be of type BOOLEAN_ATOM_INST, REL_INST or LREL_INST
    and lreln must be of type LREL_INST. REL_INST and LREL_INST are
    allowed because of the SATISFIED logical term.
*/

extern void RemoveLogRel(struct Instance *i, struct Instance *lreln);
/**< 
    Remove lreln from i's logical relation list.  If 'lreln' isn't found in
    i's logical relation list, execution continues with a warning message.
*/

ASC_DLLSPEC unsigned long WhensCount(struct Instance *i);
/**< 
    This will return the number of whens that instance "i" is referenced in.
*/

ASC_DLLSPEC struct Instance *WhensForInstance(struct Instance *i,
                                         unsigned long c);
/**<
    This routine will return the c'th when in instance i's when list.
    0 < c <= WhensCount(i).
*/

extern void AddWhen(struct Instance *i, struct Instance *when);
/**<
    Add the when instance when to instance i's when list.  when must be of
    type WHEN_INST.
*/

extern void RemoveWhen(struct Instance *i, struct Instance *when);
/**<
    Remove when from i's when list.  If 'when' isn't found in i's when
    list, execution continues with a warning message.
*/

/* @} */

#endif  /* ASC_MATHINST_H */

1	johnpye	709	/* ASCEND modelling environment
2			Copyright (C) 2006 Carnegie Mellon University
3			Copyright (C) 1990, 1993, 1994 Thomas Guthrie Epperly
4	aw0a	1
5	johnpye	709	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	aw0a	1
10	johnpye	709	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			Ascend Instance Math Object Functions.
22
23			Relation, logical relation, and When querying and assignment routines
24
25			Requires:
26			#include "utilities/ascConfig.h"
27			#include "fractions.h"
28			#include "instance_enum.h"
29			#include "compiler.h"
30			#include "dimen.h"
31			#include "expr_types.h"
32			//
33			by Tom Epperly
34			8/16/89
35			Last in CVS: $Revision: 1.8 $ $Date: 1998/05/06 17:33:37 $ $Author: ballan $
36			*/
37
38	johnpye	301	#ifndef ASC_MATHINST_H
39			#define ASC_MATHINST_H
40	aw0a	1
41	johnpye	1066	/** addtogroup compiler Compiler
42			@{
43			*/
44
45	johnpye	1063	ASC_DLLSPEC enum Expr_enum GetInstanceRelationType(CONST struct Instance *i);
46	jds	54	/**<
47	johnpye	709	This returns the type of the relation associated with this relations
48			instance (REL_INST).
49			This should be one of e_token, e_opcode, e_glassbox or e_blackbox.
50			*/
51	aw0a	1
52	johnpye	1063	ASC_DLLSPEC CONST struct relation GetInstanceRelationOnly(CONST struct Instance i);
53	jds	54	/**<
54	johnpye	709	This returns the guts of a relation instance (REL_INST).
55			These should be treated as read only usually because you don't
56			know who is sharing those guts.
57			*/
58	aw0a	1
59	johnpye	1063	ASC_DLLSPEC CONST struct relation GetInstanceRelation(CONST struct Instance i,
60	jds	54	enum Expr_enum *type);
61			/**<
62	johnpye	709	This returns the value of a relation inst(REL_INST). It will fill in
63			the type of the relation associated with this relation instance.
64			This will be one of e_token, e_opcode, e_glassbox or e_blackbox,
65			or possibly e_undefined.
66	aw0a	1
67	johnpye	709	@TODO Important! This appears not to be to inverse of the rel_instance
68			function in the solver! Why is that? -- JP
69			*/
70
71	jds	54	extern struct relation GetInstanceRelToModify(struct Instance i,
72			enum Expr_enum *type);
73			/**<
74	johnpye	709	This returns the value of a relation inst(REL_INST). In this function
75			we do not get a CONST structure and therefore we can modify it. This
76			is useful while marking conditional relations.
77			*/
78	aw0a	1
79	jds	54	extern void SetInstanceRelation(struct Instance *i,
80			struct relation *rel,
81			enum Expr_enum type);
82	ben.allan	33	/**<
83	johnpye	709	Set the relation to rel. rel will be incorporated into the instance,
84			so rel should not be modified or destroyed. The type of the relation
85			has to be provided.
86	aw0a	1
87	johnpye	709	rel and type may be the NULL/e_undefined combination.
88			*/
89
90	johnpye	1063	ASC_DLLSPEC CONST struct logrelation GetInstanceLogRelOnly(CONST struct Instancei);
91	ben.allan	33	/**<
92	johnpye	709	This returns the guts of a logical relation instance (LREL_INST).
93			These should be treated as read only usually because you don't
94			know who is sharing those guts.
95			*/
96	aw0a	1
97	johnpye	1063	ASC_DLLSPEC CONST struct logrelation GetInstanceLogRel(CONST struct Instance i);
98	ben.allan	33	/**<
99	johnpye	709	This returns the value of a logrelation inst(LREL_INST).
100			*/
101	aw0a	1
102	jds	54	extern struct logrelation GetInstanceLogRelToModify(struct Instance i);
103	ben.allan	33	/**<
104	johnpye	709	This returns the value of a logrelation inst(LREL_INST). In this function
105			we do not get a CONST structure and therefore we can modify it. This
106			is useful while marking conditional logrelations.
107			*/
108	aw0a	1
109	jds	54	extern void SetInstanceLogRel(struct Instance i, struct logrelation lrel);
110	ben.allan	33	/**<
111	johnpye	709	Set the logical relation to lrel. rel will be incorporated into the
112			instance, so rel should not be modified or destroyed.
113			*/
114	aw0a	1
115	johnpye	1063	ASC_DLLSPEC struct gl_list_t GetInstanceOperands(CONST struct Instance i);
116	ben.allan	33	/**<
117	johnpye	709	Returns list of vars/models/equations in a mathematical relationship.
118			Accepts all instance kinds. returns list only if the query makes
119			sense, but list may be empty. List is yours to destroy, but its
120			contents are not.
121			*/
122	aw0a	1
123	jds	54	extern struct gl_list_t GetInstanceWhenVars(CONST struct Instance i);
124	ben.allan	33	/**<
125	johnpye	709	This returns the list of variables associated with this when
126			instance (WHEN_INST)
127			*/
128	aw0a	1
129	jds	54	extern struct gl_list_t GetInstanceWhenCases(CONST struct Instance i);
130	ben.allan	33	/**<
131	johnpye	709	This returns the list of cases associated with this when
132			instance (WHEN_INST)
133			*/
134	aw0a	1
135	jds	54	extern struct gl_list_t GetInstanceWhens(CONST struct Instance i);
136	ben.allan	33	/**<
137	johnpye	709	This returns the list of whens associated with this instance.
138			Instance can be a model, relation,when,boolean, integer or symbol.
139			*/
140	aw0a	1
141	jds	54	extern void SetWhenVarList(struct Instance i, struct gl_list_t whenvars);
142	ben.allan	33	/**<
143	johnpye	709	Set the list of variables of a when instance to whenvars
144			*/
145	aw0a	1
146	jds	54	extern void SetWhenCases(struct Instance i, struct gl_list_t whencases);
147	ben.allan	33	/**<
148	johnpye	709	Set the list of cases of a when instance to whencases
149			*/
150	aw0a	1
151	johnpye	709	/*------------------------------------------------------------------------------
152			SPECIAL REAL ATOM FUNCTIONS
153
154			Each real instance knows what mathematical relations that it appears in.
155			That information can be acessed by the following routines.
156			Same for discrete variables.
157			*/
158	aw0a	1
159	johnpye	1063	ASC_DLLSPEC unsigned long RelationsCount(CONST struct Instance *i);
160	ben.allan	33	/**<
161	johnpye	709	This will return the number of relations that instance "i" appears in.
162			"i" must be a REAL_ATOM_INST. Otherwise, this routine will
163			bomb.
164			*/
165	aw0a	1
166	johnpye	1063	ASC_DLLSPEC struct Instance RelationsForAtom(CONST struct Instance i,
167	jds	54	unsigned long c);
168			/**<
169	johnpye	709	This routine will return the c'th relation in instance i's relation list.
170			"i" must be a REAL_ATOM_INST and 0 < c <= RelationsCount(i).
171			*/
172	aw0a	1
173	jds	54	extern void AddRelation(struct Instance i, struct Instance reln);
174	ben.allan	33	/**<
175	johnpye	709	Add the relation instance reln to instance i's relation list. "i" must
176			be of type REAL_ATOM_INST and reln must be of type REL_INST.
177			*/
178	aw0a	1
179	jds	54	extern void RemoveRelation(struct Instance i, struct Instance reln);
180	ben.allan	33	/**<
181	johnpye	709	Remove reln from i's relation list. If 'reln' isn't found in i's relation
182			list, execution continues with a warning message.
183			*/
184	aw0a	1
185	johnpye	1063	ASC_DLLSPEC unsigned long LogRelationsCount(CONST struct Instance *i);
186	ben.allan	33	/**<
187	johnpye	709	This will return the number of logical relations that instance "i"
188			appears in. "i" must be a BOOLEAN_ATOM_INST, REL_INST or LREL_INST
189			*/
190	aw0a	1
191	johnpye	1063	ASC_DLLSPEC struct Instance LogRelationsForInstance(CONST struct Instance i,
192	jds	54	unsigned long c);
193			/**<
194	johnpye	709	This routine will return the c'th logical relation in instance i's
195			logical relation list. "i" must be BOOLEAN_ATOM_INST, REL_INST or
196			LREL_INST and 0 < c <= LogRelationsCount(i).
197			*/
198	aw0a	1
199	jds	54	extern void AddLogRel(struct Instance i, struct Instance reln);
200	ben.allan	33	/**<
201	johnpye	709	Add the logical relation instance lreln to instance i's logical relation
202			list. "i" must be of type BOOLEAN_ATOM_INST, REL_INST or LREL_INST
203			and lreln must be of type LREL_INST. REL_INST and LREL_INST are
204			allowed because of the SATISFIED logical term.
205			*/
206	aw0a	1
207	jds	54	extern void RemoveLogRel(struct Instance i, struct Instance lreln);
208	ben.allan	33	/**<
209	johnpye	709	Remove lreln from i's logical relation list. If 'lreln' isn't found in
210			i's logical relation list, execution continues with a warning message.
211			*/
212	aw0a	1
213	johnpye	1063	ASC_DLLSPEC unsigned long WhensCount(struct Instance *i);
214	ben.allan	33	/**<
215	johnpye	709	This will return the number of whens that instance "i" is referenced in.
216			*/
217	aw0a	1
218	johnpye	1063	ASC_DLLSPEC struct Instance WhensForInstance(struct Instance i,
219	jds	54	unsigned long c);
220			/**<
221	johnpye	709	This routine will return the c'th when in instance i's when list.
222			0 < c <= WhensCount(i).
223			*/
224	aw0a	1
225	jds	54	extern void AddWhen(struct Instance i, struct Instance when);
226			/**<
227	johnpye	709	Add the when instance when to instance i's when list. when must be of
228			type WHEN_INST.
229			*/
230	aw0a	1
231	jds	54	extern void RemoveWhen(struct Instance i, struct Instance when);
232			/**<
233	johnpye	709	Remove when from i's when list. If 'when' isn't found in i's when
234			list, execution continues with a warning message.
235			*/
236	aw0a	1
237	johnpye	1066	/* @} */
238
239	johnpye	301	#endif /* ASC_MATHINST_H */
240	jds	54