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	johnpye	825	#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