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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 825 - (show annotations) (download) (as text)
Mon Aug 21 23:41:31 2006 UTC (16 years, 1 month ago) by johnpye
Original Path: trunk/doc/lyxFinal/howto-require.lyx
File MIME type: application/x-lyx
File size: 18105 byte(s)
Copying documentation into code tree
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{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