generic/compiler/instantiate.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 Interpreter(Instantiator).
    
    Requires:
           #include "utilities/ascConfig.h"
           #include "compiler/instance_enum.h"
           #include "compiler/fractions.h"
           #include "compiler/compiler.h"
           #include "compiler/dimen.h"
           #include "compiler/types.h"
           #include "compiler/stattypes.h"
    </pre>
*//*
    by Tom Epperly
    Created: 1/24/90
    Last in CVS: $Revision: 1.18 $ $Date: 1998/03/25 00:32:03 $ $Author: ballan $
*//** @mainpage

    @section intro_sec Introduction

    This the the code documentation for 'libascend', which contains the 'base'
    or 'core' components of the ASCEND modelling environment.

    The two main parts are the compiler and the solver. There are also a number
    of general and utilities files, as well as some 'internal' packages.

    For further information about ASCEND, see the Developers' Wiki at
    https://pse.cheme.cmu.edu/wiki/view/Ascend/WebHome

    @section license License

    ASCEND is licensed under the GNU General Public License. See the the file
    'LICENSE.txt' for more information, which is available at:
    https://pse.cheme.cmu.edu/svn-view/ascend/code/trunk/LICENSE.txt?view=markup
*/

#ifndef ASC_INSTANTIATE_H
#define ASC_INSTANTIATE_H

/** addtogroup compiler Compiler
    @{
*/

/*
 *  Relation instantiation flags.
 *  If you add/remove/change these, update the comments in
 *  SetInstantiationRelnFlags().
 */
#define NORELS   0x0
#define GBOXRELS 0x1
#define BBOXRELS 0x2
#define TOKRELS  0x4
#define ALLRELS (GBOXRELS | BBOXRELS | TOKRELS)
#define EXTRELS (GBOXRELS | BBOXRELS)

ASC_DLLSPEC long int g_compiler_counter;
/**<  Unique id of calls to instantiator. */

extern void SetInstantiationRelnFlags(unsigned int flag);
/**<
 *  Sets the relation instantiation state of the instantiator.
 *  The flags control when and how how relations are instantiated.
 *  of relations. This allows more control over the sequence in
 *  which instantiation is done, and for so-called 'phased-compilation'.
 *
 *  Valid flags are the following:
 *    - NORELS   No relations should be instantiated
 *    - GBOXRELS Glassbox relations
 *    - BBOXRELS Blackbox relations
 *    - TOKRELS  Token relations
 *    - ALLRELS  Glassbox, Blackbox, and Token relations
 *    - EXTRELS Glassbox and Blackbox relations
 */

extern unsigned int GetInstantiationRelnFlags(void);
/**<
 *  Retrieves the relation instantiation state of the instantiator.
 *  See SetInstantiationRelnFlags() for more information.
 */

/*
 *  The following define allows us to manage the development phase of
 *  the ASCEND IV instantiator so that the interface is independent
 *  of the absolute latest compiler hacks.
 *  A production interface should be written to use ONLY Instantiate
 *  and ReInstantiate macros.
 *  Hacker interfaces can define/modify Alt* functions.
 *  It is generally a dumb idea to do mix different types of
 *  Instantiate and  ReInstantiate calls on the same instance.
 */
#define Instantiate(a,b,c,d) NewInstantiate((a),(b),(c),(d))

/*
 *  The following define allows us to manage the development phase of
 *  the ASCEND IV instantiator so that the interface is independent
 *  of the absolute latest compiler hacks.
 *  A production interface should be written to use ONLY Instantiate
 *  and ReInstantiate macros.
 *  Hacker interfaces can define/modify Alt* functions.
 *  It is generally a dumb idea to do mix different types of
 *  Instantiate and  ReInstantiate calls on the same instance.
 */
#define ReInstantiate(a) NewReInstantiate(a)

extern struct Instance *NewInstantiate(symchar *type, symchar *name,
                                       int intset, symchar *defmethod);
/**<
 *  This routine will return an instance of type SIM_INST. It will make
 *  an instance of the given type this will be set as the *root* of the
 *  simulation. To access the root of the instance tree use the functions
 *  GetSimulationRoot in instquery.h
 *  intset is only used when you are making an instance of a set type.
 *  defmethod is a METHOD name we are to attempt calling
 *  on the created instance at the END of compilation. If it does not
 *  exist, we will return silently after instantiation.
 *  <pre>
 *  5 phase Algorithm (approximately. here we ignore failure modes):
 *  Phase 1
 *  level
 *  1   get type
 *  1   create sim inst
 *  1   call real_instantiate_1
 *  2   call instantiate_model_1
 *  3   steal and return universal instance of type, or
 *  3   create model instance head
 *  3   process pending instances of model
 *  4   recursive instantiate, marking rels. logrels and whens done
 *      in arrays/bitlists without actually doing them.
 *  4   if no pendings,
 *  4   else error message about parts missing,
 *     and constants undefined.
 *  ...return all the way up eventually.
 *  Go back and mark all relation statements undone, put insts pending
 *  Phase 2
 *  1   call real_instantiate_2
 *  2   call instantiate_model_2
 *  3   process pending instances of model
 *  4   recursive instantiate, doing rels only  and
 *      marking logrels and whens as done.
 *      Explain failed relations.
 *  4   All statements are now determinate,
 *           All variables must be findable or they can't be.
 *  ...return all the way up eventually.
 *  Go back and mark all logrelation statements undone, put insts pending
 *  Phase 3
 *  1   call real_instantiate_3
 *  2   call instantiate_model_3
 *  3   process pending instances of model
 *  4   recursive instantiate, doing logrels only and
 *      marking whens as done. In phase 3 there are
 *      more than 1 iteration for the instantiation of
 *      logrels, since logrels can reference logrels
 *      (logrels inside conditional statements).
 *  Explain failed logrelations.
 *  4   All logical variables and referenced rels and
 *      logrels must be findable or they can't be.
 *   ...return all the way up eventually.
 *  Go back and mark all when statements undone, put insts pending
 *  Phase 4
 *  1   call real_instantiate_4
 *  2   call instantiate_model_4
 *  3   process pending instances of model
 *  4   recursive instantiate, doing whens only.
 *  Explain failed whens.
 *  4   All conditional variables, rels or logrels
 *      referenced by the whens  must be findable or
 *      they can't be
 *  ...return all the way up eventually.
 *  Phase 5
 *      Execution of default statements. (we would like to delete phase 5).
 *  Phase 6
 *  Execute defmethod.
 *  </pre>
 */

ASC_DLLSPEC void NewReInstantiate(struct Instance *i);
/**<
 *  This routine is used to resume execution of an instance with unexecuted
 *  statements.  It will reattempt to execute the unexecuted statement.
 *  If it is able to complete the instance, it will execute the DEFAULT
 *  assignments(assignments to reals and booleans).
 */

ASC_DLLSPEC void UpdateInstance(struct Instance *root,
                           struct Instance *target,
                           CONST struct StatementList *slist);
/**<
 *  Update instance takes a pointer to the root of a simulation (ie the
 *  instance tree), and will find instance target. It will then apply
 *  the statementlist to the given to the target instance.
 *  This is the start of some experimental encapsulation/parameterization
 *  schemes.
 */

extern struct Instance *InstantiatePatch(symchar *patch,
                                         symchar *name, int intset);
/**<
 *  Instantiate patch takes the name of a patch that is supposed to be
 *  applied to a type. It partially instantiates the instance, then
 *  applies the patch. It returns the instance created. It uses
 *  UpdateInstance to do the real work. The applicability of the patch is
 *  hence determined by what that function supports.
 */

extern void ConfigureInstFromArgs(struct Instance *inst,
                                  CONST struct Instance *arginst);
/**<
 *  inst and arginst must be of the same MODEL type.
 *  inst should have NO executed statements -- it should be fresh
 *  from CreateModelInstance.
 *  Neither inst nor arginst should have any parents yet, if ever.
 *  This function copies or references, depending on how declared
 *  in the parameter list of the type for both models, the non-NULL
 *  children of arginst into inst.
 */

extern void ReConfigureInstFromArgs(struct Instance *inst,
                                             CONST struct Instance *arginst);
/**<
 *  inst and arginst must be or are about to be of the same MODEL type.
 *  inst should have been created from a less refined version of the type
 *  and is in the process of being refined up to type of arginst.
 *  arginst should not have any parents.
 *  This function copies or references, depending on how declared
 *  in the parameter list of the type for both models, the non-NULL
 *  children of arginst into inst for the slots in inst that are not
 *  already occupied.
 */

extern void LinkToParentByPos(struct Instance *parent,
                              struct Instance *child,
                              unsigned long childnum);
/**<
 *  Add child as childnumth child of parent and add parent to child.
 */

extern int IncompleteArray(CONST struct Instance *i);
/**<
 *  Given an array instance i, returns 1 if incomplete, 0 if ok.
 *  This means all NONNULL children are done, with the possible
 *  exception of arrays of relations/logical_relations.
 */

/* @} */

#endif /* ASC_INSTANTIATE_H */

1	johnpye	767	/* ASCEND modelling environment
2			Copyright (C) 2006 Carnegie Mellon University
3			Copyright (C) 1990, 1993, 1994 Thomas Guthrie Epperly
4	aw0a	1
5	johnpye	767	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	767	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			Ascend Interpreter(Instantiator).
21
22			Requires:
23			#include "utilities/ascConfig.h"
24			#include "compiler/instance_enum.h"
25			#include "compiler/fractions.h"
26			#include "compiler/compiler.h"
27			#include "compiler/dimen.h"
28			#include "compiler/types.h"
29			#include "compiler/stattypes.h"
30			</pre>
31			//
32			by Tom Epperly
33			Created: 1/24/90
34			Last in CVS: $Revision: 1.18 $ $Date: 1998/03/25 00:32:03 $ $Author: ballan $
35			//* @mainpage
36
37			@section intro_sec Introduction
38
39			This the the code documentation for 'libascend', which contains the 'base'
40			or 'core' components of the ASCEND modelling environment.
41
42			The two main parts are the compiler and the solver. There are also a number
43			of general and utilities files, as well as some 'internal' packages.
44
45			For further information about ASCEND, see the Developers' Wiki at
46			https://pse.cheme.cmu.edu/wiki/view/Ascend/WebHome
47
48			@section license License
49
50			ASCEND is licensed under the GNU General Public License. See the the file
51			'LICENSE.txt' for more information, which is available at:
52			https://pse.cheme.cmu.edu/svn-view/ascend/code/trunk/LICENSE.txt?view=markup
53			*/
54
55	johnpye	67	#ifndef ASC_INSTANTIATE_H
56			#define ASC_INSTANTIATE_H
57	aw0a	1
58	johnpye	1066	/** addtogroup compiler Compiler
59			@{
60			*/
61
62	johnpye	742	/*
63	jds	216	* Relation instantiation flags.
64	johnpye	742	* If you add/remove/change these, update the comments in
65	jds	216	* SetInstantiationRelnFlags().
66			*/
67	aw0a	1	#define NORELS 0x0
68			#define GBOXRELS 0x1
69			#define BBOXRELS 0x2
70			#define TOKRELS 0x4
71			#define ALLRELS (GBOXRELS \| BBOXRELS \| TOKRELS)
72			#define EXTRELS (GBOXRELS \| BBOXRELS)
73
74	johnpye	1063	ASC_DLLSPEC long int g_compiler_counter;
75	jds	216	/*< Unique id of calls to instantiator. /
76	aw0a	1
77	jds	54	extern void SetInstantiationRelnFlags(unsigned int flag);
78			/**<
79	jds	216	* Sets the relation instantiation state of the instantiator.
80			* The flags control when and how how relations are instantiated.
81			* of relations. This allows more control over the sequence in
82			* which instantiation is done, and for so-called 'phased-compilation'.
83			*
84			* Valid flags are the following:
85			* - NORELS No relations should be instantiated
86			* - GBOXRELS Glassbox relations
87			* - BBOXRELS Blackbox relations
88			* - TOKRELS Token relations
89			* - ALLRELS Glassbox, Blackbox, and Token relations
90			* - EXTRELS Glassbox and Blackbox relations
91	jds	54	*/
92
93	aw0a	1	extern unsigned int GetInstantiationRelnFlags(void);
94	jds	54	/**<
95	jds	216	* Retrieves the relation instantiation state of the instantiator.
96			* See SetInstantiationRelnFlags() for more information.
97	aw0a	1	*/
98
99	jds	54	/*
100			* The following define allows us to manage the development phase of
101	aw0a	1	* the ASCEND IV instantiator so that the interface is independent
102			* of the absolute latest compiler hacks.
103			* A production interface should be written to use ONLY Instantiate
104			* and ReInstantiate macros.
105			* Hacker interfaces can define/modify Alt* functions.
106			* It is generally a dumb idea to do mix different types of
107			* Instantiate and ReInstantiate calls on the same instance.
108			*/
109	jds	54	#define Instantiate(a,b,c,d) NewInstantiate((a),(b),(c),(d))
110	aw0a	1
111	jds	54	/*
112			* The following define allows us to manage the development phase of
113			* the ASCEND IV instantiator so that the interface is independent
114			* of the absolute latest compiler hacks.
115			* A production interface should be written to use ONLY Instantiate
116			* and ReInstantiate macros.
117			* Hacker interfaces can define/modify Alt* functions.
118			* It is generally a dumb idea to do mix different types of
119			* Instantiate and ReInstantiate calls on the same instance.
120			*/
121			#define ReInstantiate(a) NewReInstantiate(a)
122
123	johnpye	742	extern struct Instance NewInstantiate(symchar type, symchar *name,
124	jds	54	int intset, symchar *defmethod);
125			/**<
126	aw0a	1	* This routine will return an instance of type SIM_INST. It will make
127			* an instance of the given type this will be set as the root of the
128			* simulation. To access the root of the instance tree use the functions
129			* GetSimulationRoot in instquery.h
130			* intset is only used when you are making an instance of a set type.
131			* defmethod is a METHOD name we are to attempt calling
132			* on the created instance at the END of compilation. If it does not
133			* exist, we will return silently after instantiation.
134	jds	54	* <pre>
135	aw0a	1	* 5 phase Algorithm (approximately. here we ignore failure modes):
136			* Phase 1
137			* level
138			* 1 get type
139			* 1 create sim inst
140			* 1 call real_instantiate_1
141			* 2 call instantiate_model_1
142			* 3 steal and return universal instance of type, or
143			* 3 create model instance head
144			* 3 process pending instances of model
145			* 4 recursive instantiate, marking rels. logrels and whens done
146			* in arrays/bitlists without actually doing them.
147			* 4 if no pendings,
148			* 4 else error message about parts missing,
149			* and constants undefined.
150			* ...return all the way up eventually.
151			* Go back and mark all relation statements undone, put insts pending
152			* Phase 2
153			* 1 call real_instantiate_2
154			* 2 call instantiate_model_2
155			* 3 process pending instances of model
156			* 4 recursive instantiate, doing rels only and
157			* marking logrels and whens as done.
158			* Explain failed relations.
159			* 4 All statements are now determinate,
160			* All variables must be findable or they can't be.
161			* ...return all the way up eventually.
162			* Go back and mark all logrelation statements undone, put insts pending
163			* Phase 3
164			* 1 call real_instantiate_3
165			* 2 call instantiate_model_3
166			* 3 process pending instances of model
167			* 4 recursive instantiate, doing logrels only and
168			* marking whens as done. In phase 3 there are
169			* more than 1 iteration for the instantiation of
170			* logrels, since logrels can reference logrels
171			* (logrels inside conditional statements).
172			* Explain failed logrelations.
173			* 4 All logical variables and referenced rels and
174			* logrels must be findable or they can't be.
175			* ...return all the way up eventually.
176			* Go back and mark all when statements undone, put insts pending
177			* Phase 4
178			* 1 call real_instantiate_4
179			* 2 call instantiate_model_4
180			* 3 process pending instances of model
181			* 4 recursive instantiate, doing whens only.
182			* Explain failed whens.
183			* 4 All conditional variables, rels or logrels
184	jds	54	* referenced by the whens must be findable or
185	aw0a	1	* they can't be
186			* ...return all the way up eventually.
187			* Phase 5
188			* Execution of default statements. (we would like to delete phase 5).
189			* Phase 6
190			* Execute defmethod.
191	jds	54	* </pre>
192	aw0a	1	*/
193
194	johnpye	1063	ASC_DLLSPEC void NewReInstantiate(struct Instance *i);
195	jds	54	/**<
196	aw0a	1	* This routine is used to resume execution of an instance with unexecuted
197			* statements. It will reattempt to execute the unexecuted statement.
198			* If it is able to complete the instance, it will execute the DEFAULT
199			* assignments(assignments to reals and booleans).
200			*/
201
202	johnpye	1063	ASC_DLLSPEC void UpdateInstance(struct Instance *root,
203	jds	54	struct Instance *target,
204			CONST struct StatementList *slist);
205			/**<
206	aw0a	1	* Update instance takes a pointer to the root of a simulation (ie the
207			* instance tree), and will find instance target. It will then apply
208			* the statementlist to the given to the target instance.
209			* This is the start of some experimental encapsulation/parameterization
210			* schemes.
211			*/
212
213			extern struct Instance InstantiatePatch(symchar patch,
214	jds	54	symchar *name, int intset);
215			/**<
216	aw0a	1	* Instantiate patch takes the name of a patch that is supposed to be
217			* applied to a type. It partially instantiates the instance, then
218			* applies the patch. It returns the instance created. It uses
219			* UpdateInstance to do the real work. The applicability of the patch is
220			* hence determined by what that function supports.
221			*/
222
223	jds	54	extern void ConfigureInstFromArgs(struct Instance *inst,
224			CONST struct Instance *arginst);
225			/**<
226	aw0a	1	* inst and arginst must be of the same MODEL type.
227			* inst should have NO executed statements -- it should be fresh
228			* from CreateModelInstance.
229			* Neither inst nor arginst should have any parents yet, if ever.
230			* This function copies or references, depending on how declared
231			* in the parameter list of the type for both models, the non-NULL
232			* children of arginst into inst.
233			*/
234
235	johnpye	742	extern void ReConfigureInstFromArgs(struct Instance *inst,
236	jds	54	CONST struct Instance *arginst);
237			/**<
238	aw0a	1	* inst and arginst must be or are about to be of the same MODEL type.
239			* inst should have been created from a less refined version of the type
240			* and is in the process of being refined up to type of arginst.
241			* arginst should not have any parents.
242			* This function copies or references, depending on how declared
243			* in the parameter list of the type for both models, the non-NULL
244			* children of arginst into inst for the slots in inst that are not
245			* already occupied.
246			*/
247
248	jds	54	extern void LinkToParentByPos(struct Instance *parent,
249			struct Instance *child,
250			unsigned long childnum);
251			/**<
252	aw0a	1	* Add child as childnumth child of parent and add parent to child.
253			*/
254
255	jds	54	extern int IncompleteArray(CONST struct Instance *i);
256			/**<
257	aw0a	1	* Given an array instance i, returns 1 if incomplete, 0 if ok.
258			* This means all NONNULL children are done, with the possible
259			* exception of arrays of relations/logical_relations.
260			*/
261
262	johnpye	1066	/* @} */
263
264	johnpye	67	#endif /* ASC_INSTANTIATE_H */
265	jds	54