/[ascend]/trunk/doc/howto-require.lyx
ViewVC logotype

Annotation of /trunk/doc/howto-require.lyx

Parent Directory Parent Directory | Revision Log Revision Log


Revision 826 - (hide annotations) (download) (as text)
Tue Aug 22 01:34:33 2006 UTC (16 years, 1 month ago) by johnpye
File MIME type: application/x-lyx
File size: 18105 byte(s)
Increased max ext relations to 50.
Changed default web browser on linux to firefox.
Copied documentation files into source tree
Added build script to allow HTML and PDF generation via SCons.

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{PI*radian}*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

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22