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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

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