trunk/doc/howto-require.lyx

#LyX 1.4.1 created this file. For more info see http://www.lyx.org/
\lyxformat 245
\begin_document
\begin_header
\textclass book
\language english
\inputencoding auto
\fontscheme default
\graphics default
\paperfontsize default
\spacing single
\papersize a4paper
\use_geometry false
\use_amsmath 2
\cite_engine basic
\use_bibtopic false
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\papercolumns 1
\papersides 2
\paperpagestyle default
\tracking_changes false
\output_changes true
\end_header

\begin_body

\begin_layout Chapter
Managing model definitions, libraries, and projects 
\begin_inset LatexCommand \label{cha:require}

\end_inset


\end_layout

\begin_layout Standard
Most complex models are built from parts in one or more libraries.
 In this chapter we show typical examples of how to make sure your model
 gets the libraries it needs.
 We then explain in more general terms the ASCEND mechanism which makes
 this work and how you can use it to manage multiple modeling projects simultane
ously.
\end_layout

\begin_layout Section
Using 
\family typewriter
REQUIRE
\family default

\begin_inset LatexCommand \index{REQUIRE}

\end_inset

 and 
\family typewriter
PROVIDE
\family default

\begin_inset LatexCommand \index{PROVIDE}

\end_inset


\end_layout

\begin_layout Subsection

\family typewriter
REQUIRE
\family default
ing 
\family typewriter
system.a4l
\family default

\begin_inset LatexCommand \label{ssec:require.requireSystem.a4l}

\end_inset


\end_layout

\begin_layout Standard
Suppose you are in a great hurry and want to create a simple model and solve
 it without concern for good style, dimensional consistency, or any of the
 other hobgoblins we preach about elsewhere.
 You will write equations using only generic_real variables as defined in
 
\family typewriter
system.a4l
\family default
.
 The equations in this example do not necessarily have a solution.
 In your ascdata (see howto1) directory you create an application model
 definition file 
\begin_inset Quotes eld
\end_inset


\family typewriter
myfile.a4c
\family default
" which looks like:
\end_layout

\begin_layout LyX-Code
REQUIRE "system.a4l";
\end_layout

\begin_layout LyX-Code
MODEL quick_n_dirty;
\end_layout

\begin_layout LyX-Code
x = y^2;
\end_layout

\begin_layout LyX-Code
y = x + 2*z;
\end_layout

\begin_layout LyX-Code
z = cos(x+y);
\end_layout

\begin_layout LyX-Code
x,y,z IS_A generic_real;
\end_layout

\begin_layout LyX-Code
(* homework problem 3, due May 21.
 *)
\end_layout

\begin_layout LyX-Code
END quick_n_dirty;
\end_layout

\begin_layout Standard
The very first line 
\family typewriter
REQUIRE "system.a4l";
\family default
 tells ASCEND to find and load a file named 
\family typewriter
system.a4l
\family default
 if it has not already been loaded or provided in some other way.
 This 
\family typewriter
REQUIRE
\family default
 statement must come before the 
\family typewriter
MODEL
\family default
 which uses the 
\family typewriter
generic_real
\family default
 ATOM that 
\family typewriter
system.a4l
\family default
 defines.
 
\end_layout

\begin_layout Standard
The 
\family typewriter
REQUIRE
\family default
 statements in a file should all come at the beginning of the file before
 any other text, including comments.
 This makes it very easy for other users or automated tools to determine
 which files, if any, your models require.
\end_layout

\begin_layout Standard
On the ASCEND command line (in the Console window or xterm) or in the Script
 window, you can then enter and execute the statement
\end_layout

\begin_layout LyX-Code
READ FILE "myfile.a4c";
\end_layout

\begin_layout Standard
to cause 
\family typewriter
system.a4l
\family default
 and then 
\family typewriter
myfile.a4c
\family default
 to be loaded.
\end_layout

\begin_layout Subsection
Chaining required files
\end_layout

\begin_layout Standard
Notice when you read 
\family typewriter
myfile.a4c
\family default
 that ASCEND prints messages about the files being loaded.
 You will see that a file 
\family typewriter
basemodel.a4l
\family default
 is also loaded.
 In 
\family typewriter
system.a4l
\family default
 you will find at the beginning the statements
\end_layout

\begin_layout Standard

\family typewriter
REQUIRE "basemodel.a4l";
\end_layout

\begin_layout Standard

\family typewriter
PROVIDE "system.a4l";
\end_layout

\begin_layout Standard
The basemodel library is loaded in turn because of the 
\family typewriter
REQUIRE
\family default
 statement in 
\family typewriter
system.a4l
\family default
.
 We will come back to what the 
\family typewriter
PROVIDE
\family default
 statement does in a moment.
 This chaining can be many files deep.
 To see a more complicated example, enter
\end_layout

\begin_layout LyX-Code

\family typewriter
READ FILE column.a4l;
\end_layout

\begin_layout Standard
and watch the long list of files that gets loaded.
 If you examine the first few lines of each file in the output list, you
 will see that each file REQUIRES only the next lower level of libraries.
 This style minimizes redundant loading messages and makes it easy to substitute
 equivalent libraries in the nested lower levels without editing too many
 higher level libraries.
 The term "equivalent libraries" is defined better in the later section
 on 
\family typewriter
PROVIDE
\family default
.
\end_layout

\begin_layout Subsection
Better application modeling practice
\end_layout

\begin_layout Standard
\begin_inset Marginal
status open

\begin_layout Standard
never require system.a4l in an application model.
\end_layout

\end_inset

It is generally a bad idea to create a model using only 
\family typewriter
generic_real
\family default
 variables.
 The normal practice is to use correct units in equations and to use dimensional
 variables.
 In the following file we see that this is done by requiring 
\family typewriter
atoms.a4l
\family default
 instead of 
\family typewriter
system.a4l
\family default
 and by using correct units on the coefficients in the equations.
 
\end_layout

\begin_layout Standard

\family typewriter
REQUIRE "atoms.a4l"; MODEL quick_n_clean;
\end_layout

\begin_layout Standard

\family typewriter
x = y^2/1{PI*radian};
\end_layout

\begin_layout Standard

\family typewriter
y = x + 2{PI*radian}*z;
\end_layout

\begin_layout Standard

\family typewriter
z = cos(x+y);
\end_layout

\begin_layout Standard

\family typewriter
x, y IS_A angle;
\end_layout

\begin_layout Standard

\family typewriter
z IS_A dimensionless;
\end_layout

\begin_layout Standard

\family typewriter
(* homework problem 3, due May 21.
 *)
\end_layout

\begin_layout Standard

\family typewriter
END quick_n_clean;
\end_layout

\begin_layout Subsection
Substitute libraries
\begin_inset LatexCommand \index{substitute libraries}

\end_inset

 and 
\family typewriter
PROVIDE
\family default

\begin_inset LatexCommand \index{PROVIDE}

\end_inset


\end_layout

\begin_layout Standard
ASCEND keeps a list of the already loaded files, as we hinted at in Section
 
\begin_inset LatexCommand \ref{ssec:require.requireSystem.a4l}

\end_inset


\noun off
.
 A library file should contain a 
\family typewriter
\noun default
PROVIDE
\family default
\noun off
 statement, as 
\family typewriter
\noun default
system.a4l
\family default
\noun off
 does, telling what library it supplies.
 Normally the 
\family typewriter
\noun default
PROVIDE
\family default
\noun off
 statement just repeats the file name, but this is not always the case.
 For example, see the first few lines of the file 
\family typewriter
\noun default
ivpsystem.a4l
\family default
\noun off
, which include the statement
\end_layout

\begin_layout LyX-Code
PROVIDE "system.a4l";
\end_layout

\begin_layout Standard
indicating that 
\family typewriter
ivpsystem.a4l
\family default
 is intended to be equivalent to file 
\family typewriter
system.a4l
\family default
 while also supplying new features.
 When ivpsystem.a4l is loaded both "
\family typewriter
system.a4l
\family default
" and "
\family typewriter
ivpsystem.a4l
\family default
" get added to the list of already loaded files.
 For one explanation of when this behavior might be desirable, see Section
 
\begin_inset LatexCommand \vref{ssec:require.requireSystem.a4l}

\end_inset


\noun off
.
 Another use for this behavior is when creating and testing a second library
 to eventually replace the first one.
\end_layout

\begin_layout Standard
When a second library provides compatible but extended definitions similar
 to a first library, the second can be substituted for the first one.
 The second library will obviously have a different file name, but there
 is no need to load the first library if we already have the second one
 loaded.
 
\family typewriter
ivpsystem.a4l
\family default
 is a second library substitutable for the first library 
\family typewriter
system.a4l
\family default
.
 Note that the reverse is not true: 
\family typewriter
system.a4l
\family default
 does not 
\end_layout

\begin_layout LyX-Code
PROVIDE "ivpsystem.a4l"; 
\end_layout

\begin_layout Standard
so system is not a valid substitute for ivpsystem.
 
\end_layout

\begin_layout Subsection

\family typewriter
REQUIRE
\family default
 and combining modeling packages
\begin_inset LatexCommand \label{ssec:require.requireCombiningPackages}

\end_inset


\end_layout

\begin_layout Standard
Model libraries frequently come in interrelated groups.
 For example, the models referred to in Ben Allan's thesis are published
 electronically as a package models/ben/ in ASCEND IV release 0.9.
 To use Ben's distillation libraries, which require rather less memory than
 the current set of more flexible models, your application model should
 have the statement
\end_layout

\begin_layout LyX-Code
REQUIRE "ben/bencolumn.a4l";
\end_layout

\begin_layout Standard
at the beginning.
\end_layout

\begin_layout Standard
Combining models from different packages may be tricky if the package authors
 have not documented them well.
 Since all packages are open source code that you can copy into your ascdata
 directory and modify to suit your needs, the process of combining libraries
 usually amounts to changing the names of the conflicting model definitions
 in your copy.
 
\end_layout

\begin_layout Standard
Do NOT use 
\backslash
 instead of / in the package name given to a 
\family typewriter
REQUIRE
\family default
 statement even if you are forced to use Microsoft Windows.
 
\end_layout

\begin_layout Section
How 
\family typewriter
REQUIRE
\family default
 finds the files it loads
\end_layout

\begin_layout Standard
The file loading mechanism of 
\family typewriter
REQUIRE
\family default
 makes it simple to manage several independent sets of models in simultaneous
 development.
 We must explain this mechanism or the model management may seem somewhat
 confusing.
 When a statement is processed, ASCEND checks in a number of locations for
 a file with that name: ascdata, the current directory, and the 
\family typewriter
ascend4/models
\family default
 directory.
 We will describe how you can extend this list later.
 ASCEND also looks for model packages in each of these same locations.
 
\end_layout

\begin_layout Subsection
ascdata
\begin_inset LatexCommand \index{ascdata}

\end_inset


\end_layout

\begin_layout Standard
If your 
\family typewriter
ascdata
\family default
 directory exists and is readable, ASCEND looks there first for required
 files.
 Thus you can copy one of our standard libraries from the directory 
\family typewriter
ascend4/models
\family default
 to your 
\family typewriter
ascdata
\family default
 directory and modify it as you like.
 Your modification will be loaded instead of our standard library.
 The 
\family typewriter
ascdata
\family default

\begin_inset LatexCommand \index{ascdata}

\end_inset

 directory is typically put into your HOME
\begin_inset LatexCommand \index{HOME}

\end_inset

 directory (see Section\InsetSpace ~

\begin_inset LatexCommand \vref{ssec:atoms.newVarType}

\end_inset

).
\end_layout

\begin_layout Subsection
the current directory
\begin_inset LatexCommand \label{ssec:require.currentDir}

\end_inset


\end_layout

\begin_layout Standard
The current directory is what you get if you type 'pwd' at the ASCEND Console
 or xterm prompt.
 Under Microsoft Windows, the current directory is usually some useless
 location.
 Under UNIX, the current directory is usually the directory from which you
 started ASCEND.
\end_layout

\begin_layout Subsection
ascend4/models/
\end_layout

\begin_layout Standard
The standard (CMU) models and packages distributed with ASCEND are found
 in the 
\family typewriter
ascend4/models/
\family default
 subdirectory where ASCEND is installed.
 This directory sits next to the directory 
\family typewriter
ascend4/bin/
\family default
 where the 
\family typewriter
ascend4
\family default
 or 
\family typewriter
ascend4.exe
\family default
 executable is located.
\end_layout

\begin_layout Subsection
Multiple modeling projects
\begin_inset LatexCommand \index{multiple modeling projects}

\end_inset


\end_layout

\begin_layout Standard
If you dislike navigating multi-level directories while working on a single
 modeling project, you can separate projects by keeping all files related
 to your current project in one directory and changing to that directory
 before starting ASCEND.
 If you have files that are required in all your projects, keep those files
 in your 
\family typewriter
ascdata
\family default
 directory.
 Under Windows, 
\family typewriter
cd
\family default
 to the directory containing the current project from the Console window
 after starting ASCEND.
\end_layout

\begin_layout Subsection
Example: Finding 
\family typewriter
ben/bencolumn.a4l
\family default

\begin_inset LatexCommand \index{bencolumn.a4l}

\end_inset


\end_layout

\begin_layout Standard
Suppose an application model requires 
\family typewriter
bencolumn.a4l
\family default
 from package 
\family typewriter
ben
\family default
 as shown in Section 
\begin_inset LatexCommand \ref{ssec:require.requireCombiningPackages}

\end_inset


\noun off
.
 Normally ASCEND will execute this statement by searching for:
\end_layout

\begin_layout LyX-Code
~/ascdata/ben/bencolumn.a4l
\end_layout

\begin_layout LyX-Code
./ben/bencolumn.a4l
\end_layout

\begin_layout LyX-Code
$ASCENDDIST/ascend4/models/ben/bencolumn.a4l
\end_layout

\begin_layout Standard
Assuming we started ASCEND from directory 
\family typewriter
/usr1/ballan/projects/test1
\family default
 under UNIX, the full names of these might be
\end_layout

\begin_layout LyX-Code
/usr0/ballan/ascdata/ben/bencolumn.a4l
\end_layout

\begin_layout LyX-Code
/usr1/ballan/projects/test1/ben/bencolumn.a4l
\end_layout

\begin_layout LyX-Code
/usr/local/lib/ascend4/models/ben/bencolumn.a4l
\end_layout

\begin_layout Standard
Assuming we started ASCEND from some shortcut on a Windows desktop, the
 full names of these locations might be
\end_layout

\begin_layout LyX-Code
C:
\backslash
winnt
\backslash
profiles
\backslash
ballan
\backslash
ascdata
\backslash
ben
\backslash
bencolumn.a4l 
\end_layout

\begin_layout LyX-Code
C:
\backslash
Program Files
\backslash
netscape
\backslash
ben
\backslash
bencolumn.a4l 
\end_layout

\begin_layout LyX-Code
C:
\backslash
ASCEND
\backslash
ascend4
\backslash
models
\backslash
ben
\backslash
bencolumn.a4l
\end_layout

\begin_layout Standard
The first of these three which actually exists on your disk will be the
 file that is loaded.
\end_layout

\begin_layout Subsection
How 
\family typewriter
REQUIRE
\family default
 handles file and definition conflicts
\begin_inset LatexCommand \label{ssec:require.handleConflicts}

\end_inset


\end_layout

\begin_layout Standard
Normally you simply delete all types before loading a new or revised set
 of ASCEND models and thus you avoid most conflicts.
 When you are working with a large simulation and several smaller ones,
 you may not want to delete all the types, however.
 We decided to make 
\family typewriter
REQUIRE
\family default
 handle this situation and the almost inevitable redundant 
\family typewriter
REQUIRE
\family default
 statements that occur in the following reasonable way.
\end_layout

\begin_layout Standard
When a file is 
\family typewriter
REQUIRE
\family default
d, ASCEND first checks the list of loaded and provided files for a name
 that matches.
 If the name is found, then that file is checked to see if it has changed
 since it was loaded.
 If the file has changed, then any definition that was changed is loaded
 in the ASCEND Library and the new definition is used in building any subsequent
ly compiled simulations.
 Old simulations remain undisturbed and are not updated to use the new definitio
ns since there may be conflicts that cannot be automatically resolved.
\end_layout

\begin_layout Subsection
Extending the list of searched directories
\end_layout

\begin_layout Standard
ASCEND uses the environment variable
\begin_inset LatexCommand \index{environment variable}

\end_inset

 
\family typewriter
ASCENDLIBRARY
\family default

\begin_inset LatexCommand \index{ASCENDLIBRARY}

\end_inset

 as the list of directory paths to search for required files.
 Normally you do not set this environment variable, and ASCEND works as
 described above.
 
\end_layout

\begin_layout Standard
To see or change the value of 
\family typewriter
ASCENDLIBRARY
\family default
 that ASCEND is using, examine 
\family typewriter
ASCENDLIBRARY
\family default
 in the System utilities window available from the Script Tools menu.
 Changes made to environment variables in the utilities window are NOT saved.
 If you are clever enough to set environment variables before running ASCEND,
 you can make it look anywhere you want to put your model files.
 Consult your operating system guru for information on setting environment
 variables if you do not already know how.
\end_layout

\begin_layout Standard

\end_layout

\end_body
\end_document
1	#LyX 1.4.1 created this file. For more info see http://www.lyx.org/
2	\lyxformat 245
3	\begin_document
4	\begin_header
5	\textclass book
6	\language english
7	\inputencoding auto
8	\fontscheme default
9	\graphics default
10	\paperfontsize default
11	\spacing single
12	\papersize a4paper
13	\use_geometry false
14	\use_amsmath 2
15	\cite_engine basic
16	\use_bibtopic false
17	\paperorientation portrait
18	\secnumdepth 3
19	\tocdepth 3
20	\paragraph_separation indent
21	\defskip medskip
22	\quotes_language english
23	\papercolumns 1
24	\papersides 2
25	\paperpagestyle default
26	\tracking_changes false
27	\output_changes true
28	\end_header
29
30	\begin_body
31
32	\begin_layout Chapter
33	Managing model definitions, libraries, and projects
34	\begin_inset LatexCommand \label{cha:require}
35
36	\end_inset
37
38
39	\end_layout
40
41	\begin_layout Standard
42	Most complex models are built from parts in one or more libraries.
43	In this chapter we show typical examples of how to make sure your model
44	gets the libraries it needs.
45	We then explain in more general terms the ASCEND mechanism which makes
46	this work and how you can use it to manage multiple modeling projects simultane
47	ously.
48	\end_layout
49
50	\begin_layout Section
51	Using
52	\family typewriter
53	REQUIRE
54	\family default
55
56	\begin_inset LatexCommand \index{REQUIRE}
57
58	\end_inset
59
60	and
61	\family typewriter
62	PROVIDE
63	\family default
64
65	\begin_inset LatexCommand \index{PROVIDE}
66
67	\end_inset
68
69
70	\end_layout
71
72	\begin_layout Subsection
73
74	\family typewriter
75	REQUIRE
76	\family default
77	ing
78	\family typewriter
79	system.a4l
80	\family default
81
82	\begin_inset LatexCommand \label{ssec:require.requireSystem.a4l}
83
84	\end_inset
85
86
87	\end_layout
88
89	\begin_layout Standard
90	Suppose you are in a great hurry and want to create a simple model and solve
91	it without concern for good style, dimensional consistency, or any of the
92	other hobgoblins we preach about elsewhere.
93	You will write equations using only generic_real variables as defined in
94
95	\family typewriter
96	system.a4l
97	\family default
98	.
99	The equations in this example do not necessarily have a solution.
100	In your ascdata (see howto1) directory you create an application model
101	definition file
102	\begin_inset Quotes eld
103	\end_inset
104
105
106	\family typewriter
107	myfile.a4c
108	\family default
109	" which looks like:
110	\end_layout
111
112	\begin_layout LyX-Code
113	REQUIRE "system.a4l";
114	\end_layout
115
116	\begin_layout LyX-Code
117	MODEL quick_n_dirty;
118	\end_layout
119
120	\begin_layout LyX-Code
121	x = y^2;
122	\end_layout
123
124	\begin_layout LyX-Code
125	y = x + 2*z;
126	\end_layout
127
128	\begin_layout LyX-Code
129	z = cos(x+y);
130	\end_layout
131
132	\begin_layout LyX-Code
133	x,y,z IS_A generic_real;
134	\end_layout
135
136	\begin_layout LyX-Code
137	(* homework problem 3, due May 21.
138	*)
139	\end_layout
140
141	\begin_layout LyX-Code
142	END quick_n_dirty;
143	\end_layout
144
145	\begin_layout Standard
146	The very first line
147	\family typewriter
148	REQUIRE "system.a4l";
149	\family default
150	tells ASCEND to find and load a file named
151	\family typewriter
152	system.a4l
153	\family default
154	if it has not already been loaded or provided in some other way.
155	This
156	\family typewriter
157	REQUIRE
158	\family default
159	statement must come before the
160	\family typewriter
161	MODEL
162	\family default
163	which uses the
164	\family typewriter
165	generic_real
166	\family default
167	ATOM that
168	\family typewriter
169	system.a4l
170	\family default
171	defines.
172
173	\end_layout
174
175	\begin_layout Standard
176	The
177	\family typewriter
178	REQUIRE
179	\family default
180	statements in a file should all come at the beginning of the file before
181	any other text, including comments.
182	This makes it very easy for other users or automated tools to determine
183	which files, if any, your models require.
184	\end_layout
185
186	\begin_layout Standard
187	On the ASCEND command line (in the Console window or xterm) or in the Script
188	window, you can then enter and execute the statement
189	\end_layout
190
191	\begin_layout LyX-Code
192	READ FILE "myfile.a4c";
193	\end_layout
194
195	\begin_layout Standard
196	to cause
197	\family typewriter
198	system.a4l
199	\family default
200	and then
201	\family typewriter
202	myfile.a4c
203	\family default
204	to be loaded.
205	\end_layout
206
207	\begin_layout Subsection
208	Chaining required files
209	\end_layout
210
211	\begin_layout Standard
212	Notice when you read
213	\family typewriter
214	myfile.a4c
215	\family default
216	that ASCEND prints messages about the files being loaded.
217	You will see that a file
218	\family typewriter
219	basemodel.a4l
220	\family default
221	is also loaded.
222	In
223	\family typewriter
224	system.a4l
225	\family default
226	you will find at the beginning the statements
227	\end_layout
228
229	\begin_layout Standard
230
231	\family typewriter
232	REQUIRE "basemodel.a4l";
233	\end_layout
234
235	\begin_layout Standard
236
237	\family typewriter
238	PROVIDE "system.a4l";
239	\end_layout
240
241	\begin_layout Standard
242	The basemodel library is loaded in turn because of the
243	\family typewriter
244	REQUIRE
245	\family default
246	statement in
247	\family typewriter
248	system.a4l
249	\family default
250	.
251	We will come back to what the
252	\family typewriter
253	PROVIDE
254	\family default
255	statement does in a moment.
256	This chaining can be many files deep.
257	To see a more complicated example, enter
258	\end_layout
259
260	\begin_layout LyX-Code
261
262	\family typewriter
263	READ FILE column.a4l;
264	\end_layout
265
266	\begin_layout Standard
267	and watch the long list of files that gets loaded.
268	If you examine the first few lines of each file in the output list, you
269	will see that each file REQUIRES only the next lower level of libraries.
270	This style minimizes redundant loading messages and makes it easy to substitute
271	equivalent libraries in the nested lower levels without editing too many
272	higher level libraries.
273	The term "equivalent libraries" is defined better in the later section
274	on
275	\family typewriter
276	PROVIDE
277	\family default
278	.
279	\end_layout
280
281	\begin_layout Subsection
282	Better application modeling practice
283	\end_layout
284
285	\begin_layout Standard
286	\begin_inset Marginal
287	status open
288
289	\begin_layout Standard
290	never require system.a4l in an application model.
291	\end_layout
292
293	\end_inset
294
295	It is generally a bad idea to create a model using only
296	\family typewriter
297	generic_real
298	\family default
299	variables.
300	The normal practice is to use correct units in equations and to use dimensional
301	variables.
302	In the following file we see that this is done by requiring
303	\family typewriter
304	atoms.a4l
305	\family default
306	instead of
307	\family typewriter
308	system.a4l
309	\family default
310	and by using correct units on the coefficients in the equations.
311
312	\end_layout
313
314	\begin_layout Standard
315
316	\family typewriter
317	REQUIRE "atoms.a4l"; MODEL quick_n_clean;
318	\end_layout
319
320	\begin_layout Standard
321
322	\family typewriter
323	x = y^2/1{PI*radian};
324	\end_layout
325
326	\begin_layout Standard
327
328	\family typewriter
329	y = x + 2{PIradian}z;
330	\end_layout
331
332	\begin_layout Standard
333
334	\family typewriter
335	z = cos(x+y);
336	\end_layout
337
338	\begin_layout Standard
339
340	\family typewriter
341	x, y IS_A angle;
342	\end_layout
343
344	\begin_layout Standard
345
346	\family typewriter
347	z IS_A dimensionless;
348	\end_layout
349
350	\begin_layout Standard
351
352	\family typewriter
353	(* homework problem 3, due May 21.
354	*)
355	\end_layout
356
357	\begin_layout Standard
358
359	\family typewriter
360	END quick_n_clean;
361	\end_layout
362
363	\begin_layout Subsection
364	Substitute libraries
365	\begin_inset LatexCommand \index{substitute libraries}
366
367	\end_inset
368
369	and
370	\family typewriter
371	PROVIDE
372	\family default
373
374	\begin_inset LatexCommand \index{PROVIDE}
375
376	\end_inset
377
378
379	\end_layout
380
381	\begin_layout Standard
382	ASCEND keeps a list of the already loaded files, as we hinted at in Section
383
384	\begin_inset LatexCommand \ref{ssec:require.requireSystem.a4l}
385
386	\end_inset
387
388
389	\noun off
390	.
391	A library file should contain a
392	\family typewriter
393	\noun default
394	PROVIDE
395	\family default
396	\noun off
397	statement, as
398	\family typewriter
399	\noun default
400	system.a4l
401	\family default
402	\noun off
403	does, telling what library it supplies.
404	Normally the
405	\family typewriter
406	\noun default
407	PROVIDE
408	\family default
409	\noun off
410	statement just repeats the file name, but this is not always the case.
411	For example, see the first few lines of the file
412	\family typewriter
413	\noun default
414	ivpsystem.a4l
415	\family default
416	\noun off
417	, which include the statement
418	\end_layout
419
420	\begin_layout LyX-Code
421	PROVIDE "system.a4l";
422	\end_layout
423
424	\begin_layout Standard
425	indicating that
426	\family typewriter
427	ivpsystem.a4l
428	\family default
429	is intended to be equivalent to file
430	\family typewriter
431	system.a4l
432	\family default
433	while also supplying new features.
434	When ivpsystem.a4l is loaded both "
435	\family typewriter
436	system.a4l
437	\family default
438	" and "
439	\family typewriter
440	ivpsystem.a4l
441	\family default
442	" get added to the list of already loaded files.
443	For one explanation of when this behavior might be desirable, see Section
444
445	\begin_inset LatexCommand \vref{ssec:require.requireSystem.a4l}
446
447	\end_inset
448
449
450	\noun off
451	.
452	Another use for this behavior is when creating and testing a second library
453	to eventually replace the first one.
454	\end_layout
455
456	\begin_layout Standard
457	When a second library provides compatible but extended definitions similar
458	to a first library, the second can be substituted for the first one.
459	The second library will obviously have a different file name, but there
460	is no need to load the first library if we already have the second one
461	loaded.
462
463	\family typewriter
464	ivpsystem.a4l
465	\family default
466	is a second library substitutable for the first library
467	\family typewriter
468	system.a4l
469	\family default
470	.
471	Note that the reverse is not true:
472	\family typewriter
473	system.a4l
474	\family default
475	does not
476	\end_layout
477
478	\begin_layout LyX-Code
479	PROVIDE "ivpsystem.a4l";
480	\end_layout
481
482	\begin_layout Standard
483	so system is not a valid substitute for ivpsystem.
484
485	\end_layout
486
487	\begin_layout Subsection
488
489	\family typewriter
490	REQUIRE
491	\family default
492	and combining modeling packages
493	\begin_inset LatexCommand \label{ssec:require.requireCombiningPackages}
494
495	\end_inset
496
497
498	\end_layout
499
500	\begin_layout Standard
501	Model libraries frequently come in interrelated groups.
502	For example, the models referred to in Ben Allan's thesis are published
503	electronically as a package models/ben/ in ASCEND IV release 0.9.
504	To use Ben's distillation libraries, which require rather less memory than
505	the current set of more flexible models, your application model should
506	have the statement
507	\end_layout
508
509	\begin_layout LyX-Code
510	REQUIRE "ben/bencolumn.a4l";
511	\end_layout
512
513	\begin_layout Standard
514	at the beginning.
515	\end_layout
516
517	\begin_layout Standard
518	Combining models from different packages may be tricky if the package authors
519	have not documented them well.
520	Since all packages are open source code that you can copy into your ascdata
521	directory and modify to suit your needs, the process of combining libraries
522	usually amounts to changing the names of the conflicting model definitions
523	in your copy.
524
525	\end_layout
526
527	\begin_layout Standard
528	Do NOT use
529	\backslash
530	instead of / in the package name given to a
531	\family typewriter
532	REQUIRE
533	\family default
534	statement even if you are forced to use Microsoft Windows.
535
536	\end_layout
537
538	\begin_layout Section
539	How
540	\family typewriter
541	REQUIRE
542	\family default
543	finds the files it loads
544	\end_layout
545
546	\begin_layout Standard
547	The file loading mechanism of
548	\family typewriter
549	REQUIRE
550	\family default
551	makes it simple to manage several independent sets of models in simultaneous
552	development.
553	We must explain this mechanism or the model management may seem somewhat
554	confusing.
555	When a statement is processed, ASCEND checks in a number of locations for
556	a file with that name: ascdata, the current directory, and the
557	\family typewriter
558	ascend4/models
559	\family default
560	directory.
561	We will describe how you can extend this list later.
562	ASCEND also looks for model packages in each of these same locations.
563
564	\end_layout
565
566	\begin_layout Subsection
567	ascdata
568	\begin_inset LatexCommand \index{ascdata}
569
570	\end_inset
571
572
573	\end_layout
574
575	\begin_layout Standard
576	If your
577	\family typewriter
578	ascdata
579	\family default
580	directory exists and is readable, ASCEND looks there first for required
581	files.
582	Thus you can copy one of our standard libraries from the directory
583	\family typewriter
584	ascend4/models
585	\family default
586	to your
587	\family typewriter
588	ascdata
589	\family default
590	directory and modify it as you like.
591	Your modification will be loaded instead of our standard library.
592	The
593	\family typewriter
594	ascdata
595	\family default
596
597	\begin_inset LatexCommand \index{ascdata}
598
599	\end_inset
600
601	directory is typically put into your HOME
602	\begin_inset LatexCommand \index{HOME}
603
604	\end_inset
605
606	directory (see Section\InsetSpace ~
607
608	\begin_inset LatexCommand \vref{ssec:atoms.newVarType}
609
610	\end_inset
611
612	).
613	\end_layout
614
615	\begin_layout Subsection
616	the current directory
617	\begin_inset LatexCommand \label{ssec:require.currentDir}
618
619	\end_inset
620
621
622	\end_layout
623
624	\begin_layout Standard
625	The current directory is what you get if you type 'pwd' at the ASCEND Console
626	or xterm prompt.
627	Under Microsoft Windows, the current directory is usually some useless
628	location.
629	Under UNIX, the current directory is usually the directory from which you
630	started ASCEND.
631	\end_layout
632
633	\begin_layout Subsection
634	ascend4/models/
635	\end_layout
636
637	\begin_layout Standard
638	The standard (CMU) models and packages distributed with ASCEND are found
639	in the
640	\family typewriter
641	ascend4/models/
642	\family default
643	subdirectory where ASCEND is installed.
644	This directory sits next to the directory
645	\family typewriter
646	ascend4/bin/
647	\family default
648	where the
649	\family typewriter
650	ascend4
651	\family default
652	or
653	\family typewriter
654	ascend4.exe
655	\family default
656	executable is located.
657	\end_layout
658
659	\begin_layout Subsection
660	Multiple modeling projects
661	\begin_inset LatexCommand \index{multiple modeling projects}
662
663	\end_inset
664
665
666	\end_layout
667
668	\begin_layout Standard
669	If you dislike navigating multi-level directories while working on a single
670	modeling project, you can separate projects by keeping all files related
671	to your current project in one directory and changing to that directory
672	before starting ASCEND.
673	If you have files that are required in all your projects, keep those files
674	in your
675	\family typewriter
676	ascdata
677	\family default
678	directory.
679	Under Windows,
680	\family typewriter
681	cd
682	\family default
683	to the directory containing the current project from the Console window
684	after starting ASCEND.
685	\end_layout
686
687	\begin_layout Subsection
688	Example: Finding
689	\family typewriter
690	ben/bencolumn.a4l
691	\family default
692
693	\begin_inset LatexCommand \index{bencolumn.a4l}
694
695	\end_inset
696
697
698	\end_layout
699
700	\begin_layout Standard
701	Suppose an application model requires
702	\family typewriter
703	bencolumn.a4l
704	\family default
705	from package
706	\family typewriter
707	ben
708	\family default
709	as shown in Section
710	\begin_inset LatexCommand \ref{ssec:require.requireCombiningPackages}
711
712	\end_inset
713
714
715	\noun off
716	.
717	Normally ASCEND will execute this statement by searching for:
718	\end_layout
719
720	\begin_layout LyX-Code
721	~/ascdata/ben/bencolumn.a4l
722	\end_layout
723
724	\begin_layout LyX-Code
725	./ben/bencolumn.a4l
726	\end_layout
727
728	\begin_layout LyX-Code
729	$ASCENDDIST/ascend4/models/ben/bencolumn.a4l
730	\end_layout
731
732	\begin_layout Standard
733	Assuming we started ASCEND from directory
734	\family typewriter
735	/usr1/ballan/projects/test1
736	\family default
737	under UNIX, the full names of these might be
738	\end_layout
739
740	\begin_layout LyX-Code
741	/usr0/ballan/ascdata/ben/bencolumn.a4l
742	\end_layout
743
744	\begin_layout LyX-Code
745	/usr1/ballan/projects/test1/ben/bencolumn.a4l
746	\end_layout
747
748	\begin_layout LyX-Code
749	/usr/local/lib/ascend4/models/ben/bencolumn.a4l
750	\end_layout
751
752	\begin_layout Standard
753	Assuming we started ASCEND from some shortcut on a Windows desktop, the
754	full names of these locations might be
755	\end_layout
756
757	\begin_layout LyX-Code
758	C:
759	\backslash
760	winnt
761	\backslash
762	profiles
763	\backslash
764	ballan
765	\backslash
766	ascdata
767	\backslash
768	ben
769	\backslash
770	bencolumn.a4l
771	\end_layout
772
773	\begin_layout LyX-Code
774	C:
775	\backslash
776	Program Files
777	\backslash
778	netscape
779	\backslash
780	ben
781	\backslash
782	bencolumn.a4l
783	\end_layout
784
785	\begin_layout LyX-Code
786	C:
787	\backslash
788	ASCEND
789	\backslash
790	ascend4
791	\backslash
792	models
793	\backslash
794	ben
795	\backslash
796	bencolumn.a4l
797	\end_layout
798
799	\begin_layout Standard
800	The first of these three which actually exists on your disk will be the
801	file that is loaded.
802	\end_layout
803
804	\begin_layout Subsection
805	How
806	\family typewriter
807	REQUIRE
808	\family default
809	handles file and definition conflicts
810	\begin_inset LatexCommand \label{ssec:require.handleConflicts}
811
812	\end_inset
813
814
815	\end_layout
816
817	\begin_layout Standard
818	Normally you simply delete all types before loading a new or revised set
819	of ASCEND models and thus you avoid most conflicts.
820	When you are working with a large simulation and several smaller ones,
821	you may not want to delete all the types, however.
822	We decided to make
823	\family typewriter
824	REQUIRE
825	\family default
826	handle this situation and the almost inevitable redundant
827	\family typewriter
828	REQUIRE
829	\family default
830	statements that occur in the following reasonable way.
831	\end_layout
832
833	\begin_layout Standard
834	When a file is
835	\family typewriter
836	REQUIRE
837	\family default
838	d, ASCEND first checks the list of loaded and provided files for a name
839	that matches.
840	If the name is found, then that file is checked to see if it has changed
841	since it was loaded.
842	If the file has changed, then any definition that was changed is loaded
843	in the ASCEND Library and the new definition is used in building any subsequent
844	ly compiled simulations.
845	Old simulations remain undisturbed and are not updated to use the new definitio
846	ns since there may be conflicts that cannot be automatically resolved.
847	\end_layout
848
849	\begin_layout Subsection
850	Extending the list of searched directories
851	\end_layout
852
853	\begin_layout Standard
854	ASCEND uses the environment variable
855	\begin_inset LatexCommand \index{environment variable}
856
857	\end_inset
858
859
860	\family typewriter
861	ASCENDLIBRARY
862	\family default
863
864	\begin_inset LatexCommand \index{ASCENDLIBRARY}
865
866	\end_inset
867
868	as the list of directory paths to search for required files.
869	Normally you do not set this environment variable, and ASCEND works as
870	described above.
871
872	\end_layout
873
874	\begin_layout Standard
875	To see or change the value of
876	\family typewriter
877	ASCENDLIBRARY
878	\family default
879	that ASCEND is using, examine
880	\family typewriter
881	ASCENDLIBRARY
882	\family default
883	in the System utilities window available from the Script Tools menu.
884	Changes made to environment variables in the utilities window are NOT saved.
885	If you are clever enough to set environment variables before running ASCEND,
886	you can make it look anywhere you want to put your model files.
887	Consult your operating system guru for information on setting environment
888	variables if you do not already know how.
889	\end_layout
890
891	\begin_layout Standard
892
893	\end_layout
894
895	\end_body
896	\end_document