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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

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