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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

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