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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 826 - (show annotations) (download) (as text)
Tue Aug 22 01:34:33 2006 UTC (18 years, 3 months ago) by johnpye
File MIME type: application/x-lyx
File size: 36456 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 #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 Creating a plot
34 \begin_inset LatexCommand \index{plot}
35
36 \end_inset
37
38 (using a library model
39 \begin_inset LatexCommand \index{library model}
40
41 \end_inset
42
43
44 \begin_inset LatexCommand \index{model, library}
45
46 \end_inset
47
48 )
49 \begin_inset LatexCommand \label{cha:model3}
50
51 \end_inset
52
53
54 \end_layout
55
56 \begin_layout Standard
57 In this chapter we are going to produce a plot by using a model that someone
58 else has created.
59 We gain two lessons: (1) you will understand first hand the difficulties
60 one encounters when trying to use a model someone else has created and
61 (2) you will learn how to produce a plot in ASCEND.
62 The approach we take is not the one you should take if your goal is simply
63 to produce this plot.
64 Our goal is pedagogical
65 \begin_inset LatexCommand \index{pedagogical}
66
67 \end_inset
68
69 , not efficiency.
70 In the last chapter we created an array of vessel models to produce the
71 data that we now about to plot.
72 We approached this problem this way so you could see how one creates arrays
73 in ASCEND.
74 Having this model, we have the data.
75 The easiest thing we can do now it use it to produce a plot.
76 \end_layout
77
78 \begin_layout Standard
79 We also have in ASCEND the ability to do case studies over a model instance,
80 varying one or more of the fixed variables for it over a range of values
81 and capturing the values of other variables that result.
82 This powerful case study tool is the proper way to produce this plot as
83 ASCEND only has to compile one instance and solve it repeatedly rather
84 than produce an array of models.
85 We finish this chapter showing you how to use this case study tool.
86 \end_layout
87
88 \begin_layout Section
89 Creating a plot
90 \end_layout
91
92 \begin_layout Standard
93 We want a plot of
94 \family typewriter
95 metal_mass
96 \family default
97 values vs.
98
99 \family typewriter
100 H_to_D_ratio
101 \family default
102 .
103 If we look around at the available tools, we find there is a
104 \series bold
105 Plot
106 \series default
107 tool
108 \begin_inset LatexCommand \index{tool, Plot}
109
110 \end_inset
111
112
113 \begin_inset LatexCommand \index{Plot tool}
114
115 \end_inset
116
117 under the
118 \series bold
119 Display
120 \series default
121 button in the Browser window.
122 While not obvious, it turns out we can plot the arrays we produce when
123 we include instances of type
124 \family typewriter
125 plt_plot_integer
126 \family default
127
128 \begin_inset LatexCommand \index{plt\_plot\_integer}
129
130 \end_inset
131
132 and
133 \family typewriter
134 plt_plot_symbol
135 \family default
136
137 \begin_inset LatexCommand \index{plt\_plot\_symbol}
138
139 \end_inset
140
141 in our model.
142 We find these types in the file
143 \family typewriter
144 plot.a4l
145 \family default
146 located in the ASCEND4 models directory which is distributed with ASCEND.
147 Figure
148 \begin_inset LatexCommand \ref{fig:model3.plot.a4l}
149
150 \end_inset
151
152
153 \noun off
154 is a print out of that file (but with line numbers added so we can reference
155 them here).
156 \end_layout
157
158 \begin_layout Standard
159 \begin_inset Float figure
160 wide false
161 sideways false
162 status open
163
164 \begin_layout LyX-Code
165 REQUIRE "system.a4l";
166 \end_layout
167
168 \begin_layout LyX-Code
169 PROVIDE "plot.a4l";
170 \end_layout
171
172 \begin_layout LyX-Code
173 (* some lines removed here...
174 *)
175 \end_layout
176
177 \begin_layout LyX-Code
178
179 \end_layout
180
181 \begin_layout LyX-Code
182 (*=============================================================================*
183 \end_layout
184
185 \begin_layout LyX-Code
186 P L O T .
187 A 4 L
188 \end_layout
189
190 \begin_layout LyX-Code
191 ---------------
192 \end_layout
193
194 \begin_layout LyX-Code
195 AUTHOR:Ben Allan
196 \end_layout
197
198 \begin_layout LyX-Code
199 provoked by plot.lib by Peter Piela and Kirk A.
200 Abbott
201 \end_layout
202
203 \begin_layout LyX-Code
204 DATES:03/97 - Original code.
205 \end_layout
206
207 \begin_layout LyX-Code
208 CONTENTS:
209 \end_layout
210
211 \begin_layout LyX-Code
212 A parameterized plot library mostly compatible
213 \end_layout
214
215 \begin_layout LyX-Code
216 with plot.lib, but with variable graph titles.
217 \end_layout
218
219 \begin_layout LyX-Code
220 *)
221 \end_layout
222
223 \begin_layout LyX-Code
224 MODEL pltmodel() REFINES cmumodel();
225 \end_layout
226
227 \begin_layout LyX-Code
228 END pltmodel;
229 \end_layout
230
231 \begin_layout LyX-Code
232 MODEL plt_point(
233 \end_layout
234
235 \begin_layout LyX-Code
236 x WILL_BE real;
237 \end_layout
238
239 \begin_layout LyX-Code
240 y WILL_BE real;
241 \end_layout
242
243 \begin_layout LyX-Code
244 ) REFINES pltmodel();
245 \end_layout
246
247 \begin_layout LyX-Code
248 END plt_point;
249 \end_layout
250
251 \begin_layout LyX-Code
252 (***************************************************************)
253 \end_layout
254
255 \begin_layout LyX-Code
256 MODEL plt_curve(
257 \end_layout
258
259 \begin_layout LyX-Code
260 npnts IS_A set OF integer_constant;
261 \end_layout
262
263 \begin_layout LyX-Code
264 y_data[npnts] WILL_BE real;
265 \end_layout
266
267 \begin_layout LyX-Code
268 x_data[npnts] WILL_BE real;
269 \end_layout
270
271 \begin_layout LyX-Code
272 ) REFINES pltmodel();
273 \end_layout
274
275 \begin_layout LyX-Code
276 (* points of matching subscript will be plotted in order of
277 \end_layout
278
279 \begin_layout LyX-Code
280 * increasing subscript value.
281 \end_layout
282
283 \begin_layout LyX-Code
284 *)
285 \end_layout
286
287 \begin_layout LyX-Code
288 legendIS_A symbol; (* mutable now! *)
289 \end_layout
290
291 \begin_layout LyX-Code
292 FOR i IN [npnts] CREATE
293 \end_layout
294
295 \begin_layout LyX-Code
296 pnt[i]IS_A plt_point(x_data[i],y_data[i]);
297 \end_layout
298
299 \begin_layout LyX-Code
300 END FOR;
301 \end_layout
302
303 \begin_layout LyX-Code
304 END plt_curve;
305 \end_layout
306
307 \begin_layout LyX-Code
308 (***************************************************************)
309 \end_layout
310
311 \begin_layout LyX-Code
312 MODEL plt_plot_integer(
313 \end_layout
314
315 \begin_layout LyX-Code
316 curve_set IS_A set OF integer_constant;
317 \end_layout
318
319 \begin_layout LyX-Code
320 curve[curve_set] WILL_BE plt_curve;
321 \end_layout
322
323 \begin_layout LyX-Code
324 ) REFINES pltmodel();
325 \end_layout
326
327 \begin_layout LyX-Code
328 title, XLabel, YLabel IS_A symbol; (* mutable now! *)
329 \end_layout
330
331 \begin_layout LyX-Code
332 Xlow IS_A real;
333 \end_layout
334
335 \begin_layout LyX-Code
336 Ylow IS_A real;
337 \end_layout
338
339 \begin_layout LyX-Code
340 Xhigh IS_A real;
341 \end_layout
342
343 \begin_layout LyX-Code
344 Yhigh IS_A real;
345 \end_layout
346
347 \begin_layout LyX-Code
348 Xlog IS_A boolean;
349 \end_layout
350
351 \begin_layout LyX-Code
352 Ylog IS_A boolean;
353 \end_layout
354
355 \begin_layout LyX-Code
356 END plt_plot_integer;
357 \end_layout
358
359 \begin_layout LyX-Code
360 (***************************************************************)
361 \end_layout
362
363 \begin_layout LyX-Code
364 MODEL plt_plot_symbol(
365 \end_layout
366
367 \begin_layout LyX-Code
368 curve_set IS_A set OF symbol_constant;
369 \end_layout
370
371 \begin_layout LyX-Code
372 curve[curve_set] WILL_BE plt_curve;
373 \end_layout
374
375 \begin_layout LyX-Code
376 ) REFINES pltmodel();
377 \end_layout
378
379 \begin_layout LyX-Code
380 title, XLabel, YLabel IS_A symbol; (* mutable now! *)
381 \end_layout
382
383 \begin_layout LyX-Code
384 Xlow IS_A real;
385 \end_layout
386
387 \begin_layout LyX-Code
388 Ylow IS_A real;
389 \end_layout
390
391 \begin_layout LyX-Code
392 Xhigh IS_A real;
393 \end_layout
394
395 \begin_layout LyX-Code
396 Yhigh IS_A real;
397 \end_layout
398
399 \begin_layout LyX-Code
400 Xlog IS_A boolean;
401 \end_layout
402
403 \begin_layout LyX-Code
404 Ylog IS_A boolean;
405 \end_layout
406
407 \begin_layout LyX-Code
408 END plt_plot_symbol;
409 \end_layout
410
411 \begin_layout Caption
412 The file plot.a4l
413 \begin_inset LatexCommand \index{plot.a4l}
414
415 \end_inset
416
417
418 \begin_inset LatexCommand \label{fig:model3.plot.a4l}
419
420 \end_inset
421
422
423 \end_layout
424
425 \end_inset
426
427
428 \end_layout
429
430 \begin_layout Standard
431 As you can see, this file contains the two types we seek -- starting in
432 lines 59 and 71, respectively.
433 However, before we can use them, we do need to understand them.
434 We are, so to speak, on the receiving end of the reusability issue.
435 If you spend some time, you will find that you can decipher these model
436 definitions.
437 To make that less painful, we will help you do so here.
438 If these models were better documented, they would be much less difficult
439 to interpret.
440 In time we will add Notes to them to remedy this deficiency.
441 \end_layout
442
443 \begin_layout Subsection
444 Model refinement
445 \begin_inset LatexCommand \index{refinement}
446
447 \end_inset
448
449
450 \end_layout
451
452 \begin_layout Standard
453 \begin_inset Marginal
454 status collapsed
455
456 \begin_layout Standard
457 please, explain "refines"
458 \end_layout
459
460 \end_inset
461
462 The first model, pltmodel, is two lines long, having a MODEL statement indicatin
463 g it "refines" cmumodel and an END statement.
464 We have not encountered the concept of refinement as yet.
465 In ASCEND the to refine means the model pltmodel inherits all the statements
466 of cmumodel, a model which has been defined at the end of the file
467 \family typewriter
468 system.a4l
469 \family default
470 .
471 We show the code for cmumodel in Figure
472 \begin_inset LatexCommand \ref{fig:model3.cmumodel}
473
474 \end_inset
475
476
477 \noun off
478 , and we note that it too is an empty model.
479 It is, as it says, a root for a collection of loosely related models.
480 You will note (and forgive) a bit of dry humor by its author, Ben Allan.
481 So far as we know, this model neither provokes nor hides any bugs.
482 \end_layout
483
484 \begin_layout Standard
485 \begin_inset Float figure
486 wide false
487 sideways false
488 status open
489
490 \begin_layout LyX-Code
491 MODEL cmumodel();
492 \end_layout
493
494 \begin_layout LyX-Code
495 (* This MODEL does nothing except provide a root
496 \end_layout
497
498 \begin_layout LyX-Code
499 * for a collection of loosely related models.
500 \end_layout
501
502 \begin_layout LyX-Code
503 * If it happens to reveal a few bugs in the software,
504 \end_layout
505
506 \begin_layout LyX-Code
507 * and perhaps masks others, well, what me worry?
508 \end_layout
509
510 \begin_layout LyX-Code
511 * BAA, 8/97.
512 \end_layout
513
514 \begin_layout LyX-Code
515 *)
516 \end_layout
517
518 \begin_layout LyX-Code
519 END cmumodel;
520 \end_layout
521
522 \begin_layout Caption
523 The code for cmumodel
524 \begin_inset LatexCommand \index{cmumodel}
525
526 \end_inset
527
528
529 \begin_inset LatexCommand \label{fig:model3.cmumodel}
530
531 \end_inset
532
533
534 \end_layout
535
536 \end_inset
537
538
539 \end_layout
540
541 \begin_layout Standard
542 We need to introduce the concept of type refinement to understand these
543 models.
544 We divert for a moment to do just that.
545 \end_layout
546
547 \begin_layout Standard
548 \begin_inset Marginal
549 status collapsed
550
551 \begin_layout Standard
552 parents
553 \begin_inset LatexCommand \index{parents}
554
555 \end_inset
556
557 and children
558 \begin_inset LatexCommand \index{children}
559
560 \end_inset
561
562 in a refinement hierarchy
563 \end_layout
564
565 \end_inset
566
567 Suppose model B refines model A.
568 We call A the parent model and B the child.
569 The child model B inherits
570 \begin_inset LatexCommand \index{}
571
572 \end_inset
573
574 all the code defining the parent model A.
575 In writing the code for model B, we do not write the code it inherits from
576 A; we simply understand it is there already.
577 The code we write for model B will be only those statements that we wish
578 to add beyond the code defining its parent.
579 ASCEND supports only single inheritance; thus a child may have only one
580 parent.
581 A parent, on the other hand, may have many children, each inheriting its
582 code.
583
584 \end_layout
585
586 \begin_layout Standard
587 \begin_inset Marginal
588 status collapsed
589
590 \begin_layout Standard
591 order does not matter in nonprocedural code
592 \begin_inset LatexCommand \index{nonprocedural code}
593
594 \end_inset
595
596
597 \end_layout
598
599 \end_inset
600
601 We are dealing in ASCEND with models defined by their variables and equations.
602 As we have noted above, the order for the statements defining each of these
603 does not matter -- i.e., the variables and equations may be defined in any
604 order.
605 So adding new variables and equations through refinement may be done quite
606 easily.
607
608 \end_layout
609
610 \begin_layout Standard
611 \begin_inset Marginal
612 status collapsed
613
614 \begin_layout Standard
615 but it does in the procedural code
616 \begin_inset LatexCommand \index{procedural code}
617
618 \end_inset
619
620 for methods
621 \end_layout
622
623 \end_inset
624
625 In constrast, the methods are bits of procedural code -- i.e., they are run
626 as a sequence of statements where order does matter.
627 In ASCEND, a child model will inherit all the methods of the parent.
628 If you wish to alter the code for a method, you must replace it entirely,
629 giving it the same name as the method to be replaced.
630 (However, if you look into the documentation on the language syntax for
631 methods, you will find that the original method is still available for
632 execution.
633 You simply have to add a qualifier to its name to point to it.)
634 \end_layout
635
636 \begin_layout Standard
637 If we look into this file we see the refinement hierarchy
638 \begin_inset LatexCommand \index{refinement hierarchy}
639
640 \end_inset
641
642
643 \begin_inset LatexCommand \index{hierarchy, refinement}
644
645 \end_inset
646
647 shown in Figure
648 \begin_inset LatexCommand \ref{fig:model3.refineHierPlot.a4l}
649
650 \end_inset
651
652
653 \noun off
654 .
655
656 \noun default
657 '
658 \noun off
659 cmumodel
660 \noun default
661 '
662 \noun off
663 is the parent model for all these models.
664 pltmodel is its child.
665 The remaining three models are children of pltmodel.
666 \end_layout
667
668 \begin_layout Standard
669 \begin_inset Float figure
670 wide false
671 sideways false
672 status open
673
674 \begin_layout Standard
675
676 \noun off
677 \InsetSpace ~
678 \InsetSpace ~
679 \InsetSpace ~
680 \InsetSpace ~
681 \InsetSpace ~
682 \InsetSpace ~
683 \InsetSpace ~
684 \InsetSpace ~
685 \InsetSpace ~
686 \InsetSpace ~
687
688 \begin_inset Graphics
689 filename howto-model3Fig3.eps
690
691 \end_inset
692
693
694 \end_layout
695
696 \begin_layout Caption
697 The refinement hierarchy in the file plot.a4l
698 \begin_inset LatexCommand \label{fig:model3.refineHierPlot.a4l}
699
700 \end_inset
701
702
703 \end_layout
704
705 \end_inset
706
707
708 \end_layout
709
710 \begin_layout Standard
711 \begin_inset Marginal
712 status open
713
714 \begin_layout Standard
715 reasons for refinement
716 \end_layout
717
718 \end_inset
719
720 There are three reasons to support model refinement, with the last being
721 the most important one.
722 \end_layout
723
724 \begin_layout Itemize
725 We write more compact code
726 \begin_inset LatexCommand \index{compact code}
727
728 \end_inset
729
730 : The first reason is compactness of coding.
731 One can inherit a lot of code from a parent.
732 Only the new statements belonging to the child are then written to define
733 it.
734 This is not a very important reason for having refinement.
735 \end_layout
736
737 \begin_layout Itemize
738 Changes we make to the parent propagate
739 \begin_inset LatexCommand \index{propagate}
740
741 \end_inset
742
743 : A second reason is that one can edit changes into the parent and know
744 that the children will inherit those changes without having to alter the
745 code written for the child.
746 (Of course, one can change the parent in such a way that the changes to
747 the child are not what is wanted for the child, introducing what will likely
748 become some interesting debugging problems.)
749 \end_layout
750
751 \begin_layout Itemize
752 \begin_inset Marginal
753 status collapsed
754
755 \begin_layout Standard
756 with the most important being we know what can substitute for what
757 \end_layout
758
759 \end_inset
760
761 We know what can substitute
762 \begin_inset LatexCommand \index{substitute}
763
764 \end_inset
765
766 for what: The most important reason is that inheritance tells us what kinds
767 of parts may be substituted for a particular part in a model.
768 Because a child inherits all the code from its parent, we know the child
769 has all the variables and equations defined for it that the parent does
770 -- and typically more.
771 We can use an instance of the child as a replacement for an instance of
772 the parent.
773 Thus if you were to write a model with the part A1 of type A in it, someone
774 else can create an instance of your model and substitute a part B1 which
775 is of type B.
776 This substituted part will have all the needed variables in it that you
777 assumed would be there.
778 \end_layout
779
780 \begin_layout Standard
781 This third reason says that when a object passed as a parameter
782 \family typewriter
783 WILL_BE
784 \family default
785 of type A, we know that a part of either type A or type B will work.
786 \end_layout
787
788 \begin_layout Subsection
789 Continuing with creating a plot
790 \end_layout
791
792 \begin_layout Standard
793 We are going to include in our model a part of type
794 \family typewriter
795 plt_plot_integer
796 \family default
797 or
798 \family typewriter
799 plt_plot_symbol
800 \family default
801 that ASCEND can plot.
802 We need to look at the types of parameters required by whichever of these
803 two we select to include here.
804 Tracing back to its parents, we see them to be empty so all the code for
805 these types is right here.
806 \end_layout
807
808 \begin_layout Standard
809 The first parameter we need is a
810 \family typewriter
811 curve_set
812 \begin_inset LatexCommand \index{curve\_set}
813
814 \end_inset
815
816
817 \family default
818 which is defined to be a set of
819 \family typewriter
820 integer_constant
821 \family default
822 or of
823 \family typewriter
824 symbol_constant
825 \family default
826 .
827 We have to guess at this time at the purpose for
828 \family typewriter
829 curve_set
830 \family default
831 .
832 It would really help to have notes defining the intention here and to have
833 a piece of code that would demonstrate the use of these models.
834 At present, we do not.
835 We proceed, admitting we will appear to "know" more than we should about
836 this model.
837 It turns out that
838 \family typewriter
839 curve_set
840 \family default
841 allows us to identify each of the curves we are going to plot.
842 These models assume we are plotting several variables (let's call them
843 y[1], y[2], ...) against the same independent variable x.
844 The values for curve_set are the '1', '2', etc.
845 identifying these curves.
846 \end_layout
847
848 \begin_layout Standard
849 Here we wish to plot only one curve presenting
850 \family typewriter
851 metal_mass
852 \family default
853 vs.
854
855 \family typewriter
856 H_to_D_ratio
857 \family default
858 .
859 We can elect to use
860 \family typewriter
861 plt_plot_symbol
862 \family default
863
864 \begin_inset LatexCommand \index{plt\_plot\_symbol}
865
866 \end_inset
867
868 and label this curve '5 mm'.
869 The label '5 mm' is a symbol so we will create a set of type symbol with
870 this single member.
871 \end_layout
872
873 \begin_layout Standard
874 The second object has to be a object of type
875 \family typewriter
876 plt_curve
877 \family default
878 .
879 \end_layout
880
881 \begin_layout Standard
882 Looking at line 45, we see how to include an object of type
883 \family typewriter
884 plt_curve
885 \family default
886 .
887 It must be passed three objects: a set of integers (e.g., the set of integers
888 from 1 to 20) and two lists of data giving the y-values vs.
889 the x-values for the curve.
890 In the model tabulated_vessel_values, we have just these two lists, and
891 they are named
892 \family typewriter
893 metal_mass
894 \family default
895 and
896 \family typewriter
897 H_to_D_ratio
898 \family default
899 .
900 \end_layout
901
902 \begin_layout Standard
903
904 \noun off
905 You need now to add to the model tabulated_vessel_values
906 \noun default
907 in Figure
908 \begin_inset LatexCommand \ref{fig:model3.vesselPlot}
909
910 \end_inset
911
912
913 \noun off
914
915 \noun default
916 (it is saved as vesselPlot.a4c
917 \begin_inset LatexCommand \index{vesselPlot.a4c}
918
919 \end_inset
920
921 ).
922
923 \noun off
924 It contains a part called
925 \family typewriter
926 \noun default
927 massVSratio
928 \family default
929 \noun off
930 of type
931 \family typewriter
932 \noun default
933 plt_plot_symbol
934 \family default
935 \noun off
936
937 \begin_inset LatexCommand \index{plt\_plot\_symbol}
938
939 \end_inset
940
941 that ASCEND can plot.
942 This code is at the end of the declarative statements in tabulated_vessel_value
943 s.
944 It also replaces the first method,
945 \family typewriter
946 \noun default
947 default_self
948 \family default
949 \noun off
950 .
951 \noun default
952 ]
953 \end_layout
954
955 \begin_layout Standard
956 \begin_inset Float figure
957 wide false
958 sideways false
959 status open
960
961 \begin_layout LyX-Code
962 CurveSet "the index set for all the curves to be plotted"
963 \end_layout
964
965 \begin_layout LyX-Code
966 IS_A set OF symbol_constant;
967 \end_layout
968
969 \begin_layout LyX-Code
970 CurveSet :== ['5 mm'];
971 \end_layout
972
973 \begin_layout LyX-Code
974
975 \end_layout
976
977 \begin_layout LyX-Code
978 Curves['5 mm']
979 \end_layout
980
981 \begin_layout LyX-Code
982 "the one curve of 20 points for metal_mass
983 \backslash
984
985 \end_layout
986
987 \begin_layout LyX-Code
988 vs.
989 H_to_D_ratio"
990 \end_layout
991
992 \begin_layout LyX-Code
993 IS_A plt_curve(
994 \end_layout
995
996 \begin_layout LyX-Code
997 [1..n_entries],
998 \end_layout
999
1000 \begin_layout LyX-Code
1001 metal_mass,
1002 \end_layout
1003
1004 \begin_layout LyX-Code
1005 H_to_D_ratio
1006 \end_layout
1007
1008 \begin_layout LyX-Code
1009 );
1010 \end_layout
1011
1012 \begin_layout LyX-Code
1013 massVSratio "the object ASCEND can plot"
1014 \end_layout
1015
1016 \begin_layout LyX-Code
1017 IS_A plt_plot_symbol(
1018 \end_layout
1019
1020 \begin_layout LyX-Code
1021 CurveSet,
1022 \end_layout
1023
1024 \begin_layout LyX-Code
1025 Curves
1026 \end_layout
1027
1028 \begin_layout LyX-Code
1029 );
1030 \end_layout
1031
1032 \begin_layout LyX-Code
1033
1034 \end_layout
1035
1036 \begin_layout LyX-Code
1037 METHODS
1038 \end_layout
1039
1040 \begin_layout LyX-Code
1041 METHOD default_self;
1042 \end_layout
1043
1044 \begin_layout LyX-Code
1045 (* set the title for the plot and the labels
1046 \end_layout
1047
1048 \begin_layout LyX-Code
1049 for the ordinate and abscissa *)
1050 \end_layout
1051
1052 \begin_layout LyX-Code
1053 massVSratio.title :=
1054 \end_layout
1055
1056 \begin_layout LyX-Code
1057 'Metal mass of the walls vs H to D ratio
1058 \backslash
1059
1060 \end_layout
1061
1062 \begin_layout LyX-Code
1063 for a thin-walled cylindrical vessel';
1064 \end_layout
1065
1066 \begin_layout LyX-Code
1067 massVSratio.XLabel := 'H to D ratio';
1068 \end_layout
1069
1070 \begin_layout LyX-Code
1071 massVSratio.YLabel := 'metal mass IN kg/m^3';
1072 \end_layout
1073
1074 \begin_layout LyX-Code
1075 END default_self;
1076 \end_layout
1077
1078 \begin_layout Caption
1079 The last bit of new code to include a plot in the model tabulated_vessel_values
1080
1081 \begin_inset LatexCommand \label{fig:model3.vesselPlot}
1082
1083 \end_inset
1084
1085
1086 \end_layout
1087
1088 \end_inset
1089
1090
1091 \end_layout
1092
1093 \begin_layout Standard
1094 Also just after the first line in this file -- which reads
1095 \end_layout
1096
1097 \begin_layout LyX-Code
1098 REQUIRE "atoms.a4l";
1099 \end_layout
1100
1101 \begin_layout Standard
1102 place the instruction
1103 \end_layout
1104
1105 \begin_layout LyX-Code
1106 REQUIRE "plot.a4l";
1107 \end_layout
1108
1109 \begin_layout Standard
1110 When you solve this new instance and make massSVratio the current object,
1111 you will find the Plot tool under the Display button in the Browser window
1112 lights up and can be selected.
1113 If you do this, you will get a plot of metal_mass vs.
1114 H_to_D_ratio.
1115 A clear minimum is apparent on this plot at H_to_D_ratio equal to approximately
1116 one.
1117 \end_layout
1118
1119 \begin_layout Standard
1120 You should create a script to run this model just as you did for vesselTabulated.
1121 a4c in the previous chapter.
1122 Save it as vesselPlot.a4s.
1123 \end_layout
1124
1125 \begin_layout Section
1126 Creating a case study from a single vessel
1127 \end_layout
1128
1129 \begin_layout Standard
1130 You may think creating an array of vessels and a complex plot object just
1131 to generate a graph is either an awful lot of work or a method which will
1132 not work for very large models.
1133 You think correctly on both points.
1134 The
1135 \family typewriter
1136 plt_plot
1137 \family default
1138 models are primarily useful for sampling values from an array of inter-related
1139 models that represent a spatially distributed system such as the pillars
1140 in a bridge or the trays in a distillation column.
1141 You can conduct a case study, solving a single model over a range of values
1142 for some specified variable, using the Script command
1143 \family typewriter
1144 STUDY
1145 \family default
1146 .
1147
1148 \end_layout
1149
1150 \begin_layout Standard
1151 We will step through creating a base case and a case study using the vessel
1152 model.
1153 Start by opening a new buffer in the Script window and turning on the record
1154 button of the Scripts edit menu.
1155 In the Library window run the Delete all types button to clear out any
1156 previous simulations.
1157 Load the vessel model from the file vesselMethods.a4c you created in Section
1158 3.2.
1159
1160 \end_layout
1161
1162 \begin_layout Subsection
1163 The base case
1164 \end_layout
1165
1166 \begin_layout Standard
1167 \begin_inset Marginal
1168 status open
1169
1170 \begin_layout Standard
1171 compile a vessel
1172 \end_layout
1173
1174 \end_inset
1175
1176
1177 \end_layout
1178
1179 \begin_layout Standard
1180 Select and compile the vessel model.
1181 Give the simulation the name V.
1182 Select the simulation V in the bottom pane of the Library window and use
1183 the right mouse button (or Alt-x b) to send the simulation to the Browser.
1184 \end_layout
1185
1186 \begin_layout Standard
1187 \begin_inset Marginal
1188 status open
1189
1190 \begin_layout Standard
1191 solving the base case
1192 \end_layout
1193
1194 \end_inset
1195
1196
1197 \end_layout
1198
1199 \begin_layout Standard
1200 In the Browser, place the mouse cursor over the upper left pane.
1201 Use the right mouse button to run methods reset and values, then send the
1202 model to the Solver by typing Alt-x s.
1203 Move the mouse to the Solver window and hit the F5 key to solve the model.
1204
1205 \end_layout
1206
1207 \begin_layout Standard
1208 \begin_inset Marginal
1209 status open
1210
1211 \begin_layout Standard
1212 graphical case study optimization
1213 \end_layout
1214
1215 \end_inset
1216
1217
1218 \end_layout
1219
1220 \begin_layout Standard
1221 We now know that it takes 535.7 kg of metal to make a 250 cubic foot vessel
1222 which is twice as high as it is broad.
1223 Suppose that now we want to know the largest volume that this amount of
1224 metal can contain assuming the same wall thickness is required.
1225 Perhaps a skinnier or fatter vessel can hold more, so we need to do a case
1226 study using the aspect ratio (H_to_D_ratio) as the independent variable.
1227 Use the Browser to change V.metal_mass.fixed to TRUE, since we are using
1228 a constant amount of metal.
1229 The solver will want you to free a variable now, so select V.vessel_vol
1230 to be freed, since volume is what we want to study.
1231 \end_layout
1232
1233 \begin_layout Standard
1234 \begin_inset Marginal
1235 status open
1236
1237 \begin_layout Standard
1238 script recorded so far
1239 \end_layout
1240
1241 \end_inset
1242
1243
1244 \end_layout
1245
1246 \begin_layout Standard
1247 Turn off the recording button on the Script window.
1248 The recording should look something like
1249 \end_layout
1250
1251 \begin_layout LyX-Code
1252 DELETE TYPES;
1253 \end_layout
1254
1255 \begin_layout LyX-Code
1256 READ FILE {vesselMethods.a4c};
1257 \end_layout
1258
1259 \begin_layout LyX-Code
1260 COMPILE V OF vessel;
1261 \end_layout
1262
1263 \begin_layout LyX-Code
1264 BROWSE {V};
1265 \end_layout
1266
1267 \begin_layout LyX-Code
1268 RUN {V.reset};
1269 \end_layout
1270
1271 \begin_layout LyX-Code
1272 SOLVE {V} WITH QRSlv;
1273 \end_layout
1274
1275 \begin_layout LyX-Code
1276 ASSIGN {V.metal_mass.fixed} TRUE {};
1277 \end_layout
1278
1279 \begin_layout LyX-Code
1280 # you must type the next line in the script yourself.
1281 \end_layout
1282
1283 \begin_layout LyX-Code
1284 ASSIGN {V.vessel_vol.fixed} FALSE {};
1285 \end_layout
1286
1287 \begin_layout Standard
1288 The file ascend4/models/vesselStudy.a4s was recorded in a similar manner.
1289 \end_layout
1290
1291 \begin_layout Subsection
1292 Case study examples
1293 \end_layout
1294
1295 \begin_layout Standard
1296 \begin_inset Marginal
1297 status open
1298
1299 \begin_layout Standard
1300 configuring a case study
1301 \end_layout
1302
1303 \end_inset
1304
1305
1306 \end_layout
1307
1308 \begin_layout Standard
1309 The STUDY command takes a lot of arguments.
1310 Well explain them all momentarily, but should you forget them simply enter
1311 the command STUDY without arguments in the ASCEND Console window or xterm
1312 window to see an error message explaining the arguments and giving an example.
1313 Enter the following command in the Script window exactly as shown except
1314 for the file name following OUTFILE.
1315 Specify a file to be created in your ascdata directory.
1316 \end_layout
1317
1318 \begin_layout LyX-Code
1319 STUDY {vessel_vol}
1320 \backslash
1321
1322 \end_layout
1323
1324 \begin_layout LyX-Code
1325 IN {V}
1326 \backslash
1327
1328 \end_layout
1329
1330 \begin_layout LyX-Code
1331 VARYING {{H_to_D_ratio} {0.1} {0.5} {0.8} {1} {1.5} {2}
1332 \backslash
1333
1334 \end_layout
1335
1336 \begin_layout LyX-Code
1337 {3} {4} {8}}
1338 \backslash
1339
1340 \end_layout
1341
1342 \begin_layout LyX-Code
1343 USING {QRSlv}
1344 \backslash
1345
1346 \end_layout
1347
1348 \begin_layout LyX-Code
1349 OUTFILE {/usr0/ballan/ascdata/vvstudy.dat}
1350 \backslash
1351
1352 \end_layout
1353
1354 \begin_layout LyX-Code
1355 ERROR STOP;
1356 \end_layout
1357
1358 \begin_layout Standard
1359 This is the simplest form of case study; the backslashes at the end of each
1360 line mean that it is all one big statement.
1361 Select all these lines in the Script at once with the mouse and then hit
1362 F5 to execute the study.
1363 The solver will solve all the cases and produce the output file vvstudy.dat.
1364 The quickest way to see the result is to enter the following command in
1365 the Script, then select and execute it.
1366 (Remember to use the name of your file and not the name shown).
1367 \end_layout
1368
1369 \begin_layout LyX-Code
1370 ASCPLOT {/usr0/ballan/ascdata/vvstudy.dat};
1371 \end_layout
1372
1373 \begin_layout LyX-Code
1374 ASCPLOT CLOSE; #omit if you want to see data table
1375 \end_layout
1376
1377 \begin_layout Standard
1378 You should get a graph that looks something like Figure 4-5
1379 \begin_inset LatexCommand \ref{fig:StudyVolumeVsHtoD}
1380
1381 \end_inset
1382
1383 .
1384 The largest volume is in the neighborhood of an H_to_D_ratio of 1.
1385 \end_layout
1386
1387 \begin_layout Standard
1388 \begin_inset Float figure
1389 wide false
1390 sideways false
1391 status open
1392
1393 \begin_layout Standard
1394 \begin_inset Graphics
1395 filename howto-model3Fig5.eps
1396 scale 80
1397 BoundingBox 50bp 0bp 600bp 430bp
1398
1399 \end_inset
1400
1401
1402 \end_layout
1403
1404 \begin_layout Caption
1405 Study of Volume as Function of H/D
1406 \begin_inset LatexCommand \label{fig:StudyVolumeVsHtoD}
1407
1408 \end_inset
1409
1410
1411 \end_layout
1412
1413 \end_inset
1414
1415
1416 \end_layout
1417
1418 \begin_layout Subsubsection
1419 Multi-variable studies
1420 \end_layout
1421
1422 \begin_layout Standard
1423 We now have an idea where the solution is most interesting, so we can do
1424 a detailed study where we also monitor other variables such as surface
1425 areas.
1426 Additional variables to watch can be added to the STUDY clause of the statement.
1427 \end_layout
1428
1429 \begin_layout LyX-Code
1430 STUDY {vessel_vol} {end_area} {side_area}
1431 \backslash
1432
1433 \end_layout
1434
1435 \begin_layout LyX-Code
1436 IN {V}
1437 \backslash
1438
1439 \end_layout
1440
1441 \begin_layout LyX-Code
1442 VARYING {{H_to_D_ratio} {0.5} {0.6} {0.7} {0.8) {0.9}
1443 \backslash
1444
1445 \end_layout
1446
1447 \begin_layout LyX-Code
1448 {1} {1.1} {1.2} {1.3}}
1449 \backslash
1450
1451 \end_layout
1452
1453 \begin_layout LyX-Code
1454 USING {QRSlv}
1455 \backslash
1456
1457 \end_layout
1458
1459 \begin_layout LyX-Code
1460 OUTFILE {/usr0/ballan/ascdata/vvstudy.dat}
1461 \backslash
1462
1463 \end_layout
1464
1465 \begin_layout LyX-Code
1466 ERROR STOP;
1467 \end_layout
1468
1469 \begin_layout LyX-Code
1470 ASCPLOT {/usr0/ballan/ascdata/vvstudy.dat};
1471 \end_layout
1472
1473 \begin_layout LyX-Code
1474 ASCPLOT CLOSE; #omit if you want to see data table
1475 \end_layout
1476
1477 \begin_layout Subsubsection
1478 Multi-parameter studies
1479 \end_layout
1480
1481 \begin_layout Standard
1482 We can also do a multi-parameter study, for example also varying the wall
1483 thickness allowed.
1484 In general, any number of the fixed variables can be varied in a single
1485 study, but be aware that ASCENDs relatively simple plotting capabilities
1486 do not yet include surface or contour maps so you will need another graphic
1487 tool to view really pretty pictures.
1488 \end_layout
1489
1490 \begin_layout LyX-Code
1491 STUDY {vessel_vol}
1492 \backslash
1493
1494 \end_layout
1495
1496 \begin_layout LyX-Code
1497 IN {V}
1498 \backslash
1499
1500 \end_layout
1501
1502 \begin_layout LyX-Code
1503 VARYING
1504 \backslash
1505
1506 \end_layout
1507
1508 \begin_layout LyX-Code
1509 {{H_to_D_ratio} {0.8) {0.9} {1} {1.1} {1.2} {1.3}}
1510 \backslash
1511
1512 \end_layout
1513
1514 \begin_layout LyX-Code
1515 {{wall_thickness} {4 {mm}} {5 {mm}} {6 {mm}} {7 {mm}}}
1516 \backslash
1517
1518 \end_layout
1519
1520 \begin_layout LyX-Code
1521 USING {QRSlv}
1522 \backslash
1523
1524 \end_layout
1525
1526 \begin_layout LyX-Code
1527 OUTFILE {/usr0/ballan/ascdata/vvstudy.dat}
1528 \backslash
1529
1530 \end_layout
1531
1532 \begin_layout LyX-Code
1533 ERROR STOP;
1534 \end_layout
1535
1536 \begin_layout LyX-Code
1537 ASCPLOT {/usr0/ballan/ascdata/vvstudy.dat};
1538 \end_layout
1539
1540 \begin_layout Standard
1541 In this study the peak volume occurs at the same H_to_D_ratio for any wall
1542 thickness but the vessel volume increases for thinner walls.
1543 This may be hard to see with the default graph settings, but column 2 in
1544 rows 8-11 (H_to_D = 1.0) of the ASCPLOT data table have the largest volumes
1545 for any given thickness in column 1.
1546 Notice that the units must be specified for the wall_thickness values in
1547 the VARYING clause.
1548 \end_layout
1549
1550 \begin_layout Subsubsection
1551 Plotting output with other tools
1552 \end_layout
1553
1554 \begin_layout Standard
1555 To convert the study results from the ASCPLOT format to a file more suitable
1556 for importing into a spreadsheet, the following command does the trick.
1557 As usual, change the names to match your ascdata directory.
1558 \end_layout
1559
1560 \begin_layout LyX-Code
1561 asc_merge_data_files excel
1562 \backslash
1563
1564 \end_layout
1565
1566 \begin_layout LyX-Code
1567 {/usr0/ballan/ascdata/vvs.txt}
1568 \backslash
1569
1570 \end_layout
1571
1572 \begin_layout LyX-Code
1573 {/usr0/ballan/ascdata/vvstudy.dat}
1574 \end_layout
1575
1576 \begin_layout Standard
1577 If you prefer Matlab style text, substitute matlab for excel in the line
1578 above and change the output name from vvs.txt to vvs.m.
1579 \end_layout
1580
1581 \begin_layout Subsection
1582 STUDY behavior details
1583 \end_layout
1584
1585 \begin_layout Standard
1586 \begin_inset Marginal
1587 status open
1588
1589 \begin_layout Standard
1590 variable list
1591 \end_layout
1592
1593 \end_inset
1594
1595
1596 \end_layout
1597
1598 \begin_layout Standard
1599 We now turn to the details of the STUDY statement.
1600 As we saw in Section 4.2.2.1, any number of variables to be monitored can
1601 follow the STUDY keyword.
1602
1603 \end_layout
1604
1605 \begin_layout Standard
1606 \begin_inset Marginal
1607 status open
1608
1609 \begin_layout Standard
1610 IN clause
1611 \end_layout
1612
1613 \end_inset
1614
1615
1616 \end_layout
1617
1618 \begin_layout Standard
1619 The IN clause specifies which part of a simulation is to be sent to the
1620 Solver; a small part of a much larger model can be studied if you so desire.
1621 All the variable and parameter names that follow the STUDY keyword and
1622 that appear in the VARYING clause must be found in this part of the simulation.
1623
1624 \end_layout
1625
1626 \begin_layout Standard
1627 \begin_inset Marginal
1628 status open
1629
1630 \begin_layout Standard
1631 parameter list
1632 \end_layout
1633
1634 \end_inset
1635
1636
1637 \end_layout
1638
1639 \begin_layout Standard
1640 The VARYING clauses is a list of lists.
1641 Each inner list gives the name of the parameter to vary followed by its
1642 list of values.
1643 Each possible combination of parameter values will be attempted in multi-parame
1644 ter studies.
1645 If a case fails to solve, then the study will behave according to the option
1646 set in the ERROR clause.
1647 \end_layout
1648
1649 \begin_layout Standard
1650 \begin_inset Marginal
1651 status open
1652
1653 \begin_layout Standard
1654 solver name
1655 \end_layout
1656
1657 \end_inset
1658
1659
1660 \end_layout
1661
1662 \begin_layout Standard
1663 The solver named in the USING clause is invoked on each case.
1664 The solver may be any of the algebraic solvers or optimizers, but the integrato
1665 rs (e.g.
1666 LSODE) are not allowed.
1667
1668 \end_layout
1669
1670 \begin_layout Standard
1671 \begin_inset Marginal
1672 status open
1673
1674 \begin_layout Standard
1675 data file name
1676 \end_layout
1677
1678 \end_inset
1679
1680
1681 \end_layout
1682
1683 \begin_layout Standard
1684 The case data are stored in the file name which appears in the OUTFILE clause.
1685 By default, this file is overwritten when a STUDY is started, so if you
1686 want multiple result files, use separate file names.
1687 \end_layout
1688
1689 \begin_layout Standard
1690 \begin_inset Marginal
1691 status open
1692
1693 \begin_layout Standard
1694 error handling
1695 \end_layout
1696
1697 \end_inset
1698
1699
1700 \end_layout
1701
1702 \begin_layout Standard
1703 When the solver fails to converge or encounters an error, the STUDY can
1704 either ignore it (ERROR IGNORE) and go on to the next case, warn you (ERROR
1705 WARN) and go on to the next case, or stop (ERROR STOP).
1706 The ERROR option makes it possible start a case study and go to lunch.
1707 Cases which fail to solve will not appear in the output data file.
1708 \end_layout
1709
1710 \begin_layout Standard
1711 Note that if the model is numerically ill-behaved it is possible for a case
1712 to fail when there is in fact a solution for that combination of parameters.
1713 STUDY uses the solution of the last successfully solved case as the initial
1714 guess for the next case, but sometimes this is not the best strategy.
1715 STUDY also does not attempt to rescale the problem from case to case.
1716 When a case that you think should succeed fails, go back and investigate
1717 that region of the model again manually or with a more narrowly defined
1718 study.
1719 \end_layout
1720
1721 \begin_layout Section
1722 Discussion
1723 \end_layout
1724
1725 \begin_layout Standard
1726 We have just led you step by step through the process of creating, debugging
1727 and solving a small ASCEND model.
1728 We then showed you how to make this model more reusable, first by adding
1729 comments and methods.
1730 Methods capture the "how you got it well-posed" experience you had when
1731 first solving an instance of the vessel model.
1732 We then showed you how to parameterize this model and then use it to construct
1733 a table of
1734 \family typewriter
1735 metal_mass
1736 \family default
1737 values vs.
1738
1739 \family typewriter
1740 H_to_D_ratio
1741 \family default
1742 values.
1743 Finally we showed you how to add a plot of these results.
1744 You should next look at the chapter in the documentation where you create
1745 two more small ASCEND models.
1746 This chapter gives you much less detail on the buttons to push.
1747 Finally, if you are a chemical engineer, you should look at the chapter
1748 on the script and model for a simple flowsheet (
1749 \family typewriter
1750 simple_fs.a4s
1751 \family default
1752 and
1753 \family typewriter
1754 simple_fs.a4c
1755 \family default
1756 respectively).
1757
1758 \end_layout
1759
1760 \begin_layout Standard
1761 With this experience you should be ready to write your own simple ASCEND
1762 models to solve problems that you might now think of solving using a spreadshee
1763 t.
1764 Remember that once you have the model debugged in ASCEND, you can solve
1765 inside out, backwards and upside down and NOT just the way you first posed
1766 it -- unlike your typical use of a spreadsheet model.
1767 \end_layout
1768
1769 \end_body
1770 \end_document

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