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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1385 - (show annotations) (download) (as text)
Sat Apr 7 09:13:41 2007 UTC (15 years, 2 months ago) by jpye
File MIME type: application/x-lyx
File size: 39773 byte(s)
Some work on adding 'listing' support in the ASCEND manual.
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 Preparing a model for reuse
80 \begin_inset LatexCommand \index{reuse}
81
82 \end_inset
83
84
85 \begin_inset LatexCommand \label{cha:model2}
86
87 \end_inset
88
89
90 \end_layout
91
92 \begin_layout Standard
93 There are four major ways to prepare a model for reuse.
94 First, you should add comments to a model.
95 Second, you should add methods to a model definition to pass to a future
96 user your experience in creating an instance of this type which is well-posed.
97 Third, you should parameterize the model type definition to alert a future
98 user as to which parts of this model you deem to be the most likely to
99 be shared.
100 And fourth, you should prepare a script that a future user can run to solve
101 a sample problem involving an instance of the model.
102 We shall consider each of these items in turn in what follows.
103 \begin_inset Foot
104 status open
105
106 \begin_layout Standard
107 More detail on these is available in papers and reports by Allan, Zaher,
108 Chittur et al
109 \begin_inset LatexCommand \cite{Allan1997d}
110
111 \end_inset
112
113 ,
114 \begin_inset LatexCommand \cite{Allan1997b}
115
116 \end_inset
117
118 ,
119 \begin_inset LatexCommand \cite{Allan1997}
120
121 \end_inset
122
123 ,
124 \begin_inset LatexCommand \cite{Krishnan1993}
125
126 \end_inset
127
128 ,
129 \begin_inset LatexCommand \cite{Zaher1991}
130
131 \end_inset
132
133 .
134 \end_layout
135
136 \end_inset
137
138
139 \end_layout
140
141 \begin_layout Section
142 Adding comments
143 \begin_inset LatexCommand \index{comments}
144
145 \end_inset
146
147 and notes
148 \begin_inset LatexCommand \index{notes}
149
150 \end_inset
151
152
153 \end_layout
154
155 \begin_layout Standard
156 In ASCEND we can create traditional comments for a model -- i.e., add text
157 to the code that aids anyone looking at the code to understand what is
158 there.
159 We do this by enclosing text with the delimiters
160 \family typewriter
161 (*
162 \family default
163
164 \begin_inset LatexCommand \index{(*}
165
166 \end_inset
167
168 and
169 \family typewriter
170 *)
171 \family default
172
173 \begin_inset LatexCommand \index{*)}
174
175 \end_inset
176
177 .
178 Thus the line
179 \end_layout
180
181 \begin_layout LyX-Code
182 \begin_inset ERT
183 status open
184
185 \begin_layout Standard
186
187
188 \backslash
189 begin{ascend}
190 \end_layout
191
192 \begin_layout Standard
193
194 (* This is a comment *)
195 \end_layout
196
197 \begin_layout Standard
198
199
200 \backslash
201 end{ascend}
202 \end_layout
203
204 \end_inset
205
206
207 \end_layout
208
209 \begin_layout Standard
210 is a comment in ASCEND.
211 Traditional comments are only visible when we display the code using the
212 Display code tool
213 \begin_inset LatexCommand \index{Display code tool}
214
215 \end_inset
216
217
218 \begin_inset LatexCommand \index{tool, Display code}
219
220 \end_inset
221
222 in the Library window or when we view the code in the text editor we used
223 to create it.
224
225 \end_layout
226
227 \begin_layout Standard
228 We suggest we can do more for the modeler with the concept of Notes, a form
229 of "active" comments available in ASCEND.
230 ASCEND has tools to extract notes and display them in searchable form.
231 \end_layout
232
233 \begin_layout Standard
234 \begin_inset LatexCommand \index{comments, active}
235
236 \end_inset
237
238 In Figure
239 \begin_inset LatexCommand \ref{fig:model2.vesselWithNotes}
240
241 \end_inset
242
243
244 \noun off
245 we show two types of notes the modeler can add.
246
247 \series bold
248 \noun default
249 Longer notes
250 \series default
251 \noun off
252 are set off in block style starting with the keyword
253 \family sans
254 \noun default
255 NOTES
256 \family default
257 \noun off
258 and ending with
259 \family sans
260 \noun default
261 END NOTES
262 \family default
263 \noun off
264 .
265 In this model, we declare two notes in this manner: (1) to indicate who
266 the author is and (2) to indicate the creation date for this model.
267 Note that the notes are director to documenting
268 \family sans
269 \noun default
270 SELF
271 \family default
272 \noun off
273 , which is the model itself -- i.e., the vessel model as a whole object.
274 The object one documents can be any instance in the model -- any variable,
275 equation or part.
276 The tools for handling notes can sort on the terms enclosed in single quotes
277 so one could, for example, isolate the author notes for all the models.
278 \end_layout
279
280 \begin_layout Standard
281 Vessel model with
282 \family sans
283 NOTES
284 \family default
285 added (model
286 \family typewriter
287 vesselNotes.a4c
288 \family default
289
290 \begin_inset LatexCommand \index{vesselNotes.a4c}
291
292 \end_inset
293
294 )
295 \begin_inset LatexCommand \label{fig:model2.vesselWithNotes}
296
297 \end_inset
298
299
300 \end_layout
301
302 \begin_layout Standard
303 \begin_inset ERT
304 status open
305
306 \begin_layout Standard
307
308
309 \backslash
310 lstset{language=ASCEND}
311 \end_layout
312
313 \begin_layout Standard
314
315
316 \backslash
317 lstinputlisting[firstline=24]{../models/vesselNotes.a4c}
318 \end_layout
319
320 \begin_layout Standard
321
322 \end_layout
323
324 \end_inset
325
326
327 \end_layout
328
329 \begin_layout Standard
330 A user may use any term desired in the single quotes.
331 We have not decided yet what the better set of terms should be so we do
332 not as yet suggest any.
333 With time we expect the terms used to settle down to just a few that are
334 repeated for all the models in a library.
335 \end_layout
336
337 \begin_layout Standard
338 There are also
339 \series bold
340 short notes
341 \series default
342 we can attach to every variable in the model.
343 A "one liner
344 \begin_inset LatexCommand \index{notes, one liner}
345
346 \end_inset
347
348
349 \begin_inset LatexCommand \index{one liner}
350
351 \end_inset
352
353 " in double quotes just following the variable name allows the automatic
354 annotation of variables in reports.
355 \end_layout
356
357 \begin_layout Standard
358 The last few lines of Figure
359 \begin_inset LatexCommand \ref{fig:model2.vesselWithNotes}
360
361 \end_inset
362
363
364 \noun off
365 shows adding
366 \series bold
367 \noun default
368 separate notes
369 \series default
370 \noun off
371 we write using
372 \family sans
373 \noun default
374 ADD NOTES IN
375 \family default
376 \noun off
377 syntax
378 \begin_inset LatexCommand \index{ADD NOTES IN object}
379
380 \end_inset
381
382 .
383 This object can appear before or after or in a different file from the
384 object it describes.
385 This style of note writing is useful as it allows another person to add
386 notes to a model without changing the code for a model.
387 Thus it allows several different sets of notes to exist for a single model,
388 with the choice of which to use being up to the person maintaining the
389 model library.
390 Finally, it allows one to eliminate the "clutter" the documentation often
391 adds to the code.
392 \end_layout
393
394 \begin_layout Section
395 Adding methods
396 \begin_inset LatexCommand \index{methods, adding}
397
398 \end_inset
399
400
401 \begin_inset LatexCommand \index{adding methods}
402
403 \end_inset
404
405
406 \end_layout
407
408 \begin_layout Standard
409 We would next like to pass along our experiences in getting this model to
410 be well-posed -- i.e., we would like to tell future users which variables
411 we decided to fix and which we decided to calculate.
412 We would also like to provide some typical values for the variables we
413 decided to fix.
414 ASCEND allows us to attach any number of methods to a type definition.
415 Methods are procedural code that we can request be run through the interface
416 while browsing a model instance.
417 We shall include methods as described in Table
418 \begin_inset LatexCommand \ref{tab:model2.reqdMethods}
419
420 \end_inset
421
422
423 \noun off
424 to set just the right fixed flags and variable values for an instance of
425 our vessel model to be well-posed.
426 \end_layout
427
428 \begin_layout Standard
429 The system has defaults definitions for all these methods.
430 You already saw that to be true if you went through the process of setting
431 all the fixed flags to FALSE in the previous chapter.
432 In case you did not, load and compile the vesselPlain.a4c model in ASCEND.
433 Export the compiled instance to the Browser.
434 Then in the Browser, under the Edit button, select Run method.
435 You will see a list containing these and other methods we shall be describing
436 shortly.
437 Select specify and hit the OK button.
438 Then look in the Console window.
439 A message similar to the following will appear, with all but the first
440 line being in red to signify you should pay attention to the message:
441 \end_layout
442
443 \begin_layout LyX-Code
444 Running method specify in v
445 \end_layout
446
447 \begin_layout LyX-Code
448 Found STOP
449 \begin_inset LatexCommand \index{STOP}
450
451 \end_inset
452
453 statement in METHOD
454 \end_layout
455
456 \begin_layout LyX-Code
457 C:
458 \backslash
459 PROGRAM FILES
460 \backslash
461 ASCEND
462 \backslash
463 ASCEND4
464 \backslash
465 models
466 \backslash
467 basemodel.a4l:307
468 \end_layout
469
470 \begin_layout LyX-Code
471 STOP {Error
472 \begin_inset LatexCommand \index{error}
473
474 \end_inset
475
476 ! Standard method "specify" called but not
477 \end_layout
478
479 \begin_layout LyX-Code
480 written in MODEL.};
481 \end_layout
482
483 \begin_layout Standard
484 This message is telling you that you have just run the default specify method
485 \begin_inset LatexCommand \index{specify method, default}
486
487 \end_inset
488
489 .
490 We have to hand-craft every specify method so the default method is not
491 appropriate.
492 This message is alerting us to the fact that we did not yet write a special
493 specify method for this model type.
494 \end_layout
495
496 \begin_layout Standard
497 Try running the ClearAll
498 \begin_inset LatexCommand \index{ClearAll}
499
500 \end_inset
501
502 method.
503 The default ClearAll method is always the one you will want so it does
504 not put out a message to alert you that it is the default.
505
506 \end_layout
507
508 \begin_layout Standard
509 \begin_inset Float table
510 wide false
511 sideways false
512 status open
513
514 \begin_layout Caption
515 \begin_inset LatexCommand \label{tab:model2.reqdMethods}
516
517 \end_inset
518
519 Some of the methods
520 \begin_inset LatexCommand \index{methods, required}
521
522 \end_inset
523
524 we require for putting a model into an ASCEND library
525 \end_layout
526
527 \begin_layout Standard
528 \begin_inset Tabular
529 <lyxtabular version="3" rows="5" columns="2">
530 <features>
531 <column alignment="center" valignment="top" leftline="true" width="1.25in">
532 <column alignment="center" valignment="top" leftline="true" rightline="true" width="3.5in">
533 <row topline="true" bottomline="true">
534 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
535 \begin_inset Text
536
537 \begin_layout Standard
538
539 \end_layout
540
541 \end_inset
542 </cell>
543 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
544 \begin_inset Text
545
546 \begin_layout Standard
547
548 \end_layout
549
550 \end_inset
551 </cell>
552 </row>
553 <row topline="true">
554 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
555 \begin_inset Text
556
557 \begin_layout Standard
558
559 \family typewriter
560 ClearAll
561 \family default
562
563 \begin_inset LatexCommand \index{ClearAll}
564
565 \end_inset
566
567
568 \end_layout
569
570 \end_inset
571 </cell>
572 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
573 \begin_inset Text
574
575 \begin_layout Standard
576 a method to set all the .fixed flags for variables in the type to FALSE.
577 This puts these flags into a known standard state -- i.e., all are FALSE.
578 All models inherit this method from the base model and the need to rewrite
579 it is very, very rare.
580 \end_layout
581
582 \end_inset
583 </cell>
584 </row>
585 <row topline="true">
586 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
587 \begin_inset Text
588
589 \begin_layout Standard
590
591 \family typewriter
592 specify
593 \family default
594
595 \begin_inset LatexCommand \index{specify}
596
597 \end_inset
598
599
600 \end_layout
601
602 \end_inset
603 </cell>
604 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
605 \begin_inset Text
606
607 \begin_layout Standard
608
609 \family roman
610 \series medium
611 \shape up
612 \size normal
613 \emph off
614 \bar no
615 \noun off
616 \color none
617 a method which assumes all the fixed flags are currently FALSE and which
618 then sets a suitable set of fixed flags to TRUE to make an instance of
619 this type of model well-posed.
620 A well-posed model is one that is square (n equations in n unknowns) and
621 solvable.
622 \end_layout
623
624 \end_inset
625 </cell>
626 </row>
627 <row topline="true">
628 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
629 \begin_inset Text
630
631 \begin_layout Standard
632
633 \family typewriter
634 reset
635 \family default
636
637 \begin_inset LatexCommand \index{reset}
638
639 \end_inset
640
641
642 \end_layout
643
644 \end_inset
645 </cell>
646 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
647 \begin_inset Text
648
649 \begin_layout Standard
650
651 \family roman
652 \series medium
653 \shape up
654 \size normal
655 \emph off
656 \bar no
657 \noun off
658 \color none
659 a method which first runs the ClearAll method and then the specify method.
660 We include this method because it is very convenient.
661 We only have to run one method to make any simulation well-posed, no matter
662 how its fixed flags are currently set.
663 All models inherit this method from the base model, as with ClearAll .
664 It should only rarely have to be rewritten for a model.
665 \end_layout
666
667 \end_inset
668 </cell>
669 </row>
670 <row topline="true" bottomline="true">
671 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
672 \begin_inset Text
673
674 \begin_layout Standard
675
676 \family typewriter
677 values
678 \family default
679
680 \begin_inset LatexCommand \index{values}
681
682 \end_inset
683
684
685 \end_layout
686
687 \end_inset
688 </cell>
689 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
690 \begin_inset Text
691
692 \begin_layout Standard
693
694 \family roman
695 \series medium
696 \shape up
697 \size normal
698 \emph off
699 \bar no
700 \noun off
701 \color none
702 a method to establish typical values for the variables we have fixed in
703 an application or test model.
704 We may also supply values for some of the variables we will be computing
705 to aid in solving a model instance of this type.
706 These values reflectiveness that we have tested for a simulation of this
707 type and found to work.
708 \end_layout
709
710 \end_inset
711 </cell>
712 </row>
713 </lyxtabular>
714
715 \end_inset
716
717
718 \end_layout
719
720 \end_inset
721
722
723 \end_layout
724
725 \begin_layout Standard
726 To write the
727 \family typewriter
728 specify
729 \family default
730 and
731 \family typewriter
732 values
733 \family default
734 methods for our vessel model, we note that we have successfully solved
735 the vessel model in at least two different ways above.
736 Thus both variations are examples of being `well-posed'.
737 We can choose which variation we shall use when creating the
738 \family typewriter
739 specify
740 \family default
741 method for our vessel type definition.
742 Let us choose the alternative where we fixed
743 \family typewriter
744 vessel_volume
745 \family default
746 ,
747 \family typewriter
748 H_to_D_ratio
749 \family default
750 ,
751 \family typewriter
752 metal_density
753 \family default
754 and
755 \family typewriter
756 wall_thickness
757 \family default
758 and provided them with the values of
759 \family typewriter
760 250 ft^3
761 \family default
762 ,
763 \family typewriter
764 3
765 \family default
766 ,
767 \family typewriter
768 5000 kg/m^3
769 \family default
770 and
771 \family typewriter
772 5 mm
773 \family default
774 respectively to be our `standard' specification.
775 Default methods
776 \family typewriter
777 ClearAll
778 \family default
779 and
780 \family typewriter
781 reset
782 \family default
783 are appropriate
784 \end_layout
785
786 \begin_layout Standard
787 As already noted, the purpose of
788 \family typewriter
789 ClearAll
790 \family default
791 is to set all the variables to
792 \family sans
793 FREE
794 \family default
795 , a well-defined state from which we can start over to set variables
796 \family sans
797 FIX
798 \family default
799 ed as we wish.
800 The method
801 \family typewriter
802 reset
803 \family default
804 simply runs
805 \family typewriter
806 ClearAll
807 \family default
808 followed by the
809 \family typewriter
810 specify
811 \family default
812 method for a model.
813 The default versions for these two methods are generally exactly what one
814 wants so one need not write these.
815 \end_layout
816
817 \begin_layout Standard
818 Figure
819 \begin_inset LatexCommand \ref{fig:model2.vesselWithMethods}
820
821 \end_inset
822
823
824 \noun off
825 illustrates our vessel model with our local versions added for
826 \family typewriter
827 \noun default
828 specify
829 \family default
830 \noun off
831 and
832 \family typewriter
833 \noun default
834 values
835 \family default
836 \noun off
837 .
838 Look only at these for the moment and note that they do what we described
839 above.
840 We show some other methods we shall explain in a moment.
841 \end_layout
842
843 \begin_layout Standard
844 Version of vessel with
845 \family sans
846 METHODS
847 \family default
848 added (
849 \family typewriter
850 vesselMethods.a4c
851 \family default
852
853 \begin_inset LatexCommand \index{vesselMethods.a4c}
854
855 \end_inset
856
857 )
858 \begin_inset LatexCommand \label{fig:model2.vesselWithMethods}
859
860 \end_inset
861
862
863 \end_layout
864
865 \begin_layout Standard
866 \begin_inset ERT
867 status open
868
869 \begin_layout Standard
870
871
872 \backslash
873 lstset{language=ASCEND}
874 \end_layout
875
876 \begin_layout Standard
877
878
879 \backslash
880 lstinputlisting[firstline=23]{../models/vesselMethods.a4c}
881 \end_layout
882
883 \end_inset
884
885
886 \end_layout
887
888 \begin_layout Standard
889 In Table
890 \begin_inset LatexCommand \ref{tab:model2.addedReqdMethods}
891
892 \end_inset
893
894
895 \noun off
896 we describe additional methods we require before we will put a model into
897 one of our libraries.
898 Each of these had two versions, both of which we require.
899 The designation _self
900 \begin_inset LatexCommand \index{\_self}
901
902 \end_inset
903
904 is for a method to do something for all the variables and/or parts we have
905 defined locally within the current model with an IS_A statement.
906 The designation _all
907 \begin_inset LatexCommand \index{\_all}
908
909 \end_inset
910
911 is for a method to do something for parts that are defined within an "outer"
912 model that has an instance of this model as a part.
913 The "outer" model is at a higher scope
914 \begin_inset LatexCommand \index{scope}
915
916 \end_inset
917
918 .
919 It can share its parts with this model by passing them in as parameters,
920 a topic we cover shortly in
921 \noun default
922 Section
923 \noun off
924
925 \begin_inset LatexCommand \ref{sec:model2.parameterizingVessel}
926
927 \end_inset
928
929 .
930
931 \noun default
932
933 \noun off
934 Only the _self versions of these methods are relevant here and are in
935 \noun default
936 Figure
937 \noun off
938
939 \begin_inset LatexCommand \ref{fig:model2.vesselWithMethods}
940
941 \end_inset
942
943 .
944 \end_layout
945
946 \begin_layout Standard
947 \begin_inset Float table
948 wide false
949 sideways false
950 status open
951
952 \begin_layout Caption
953 Additional methods
954 \begin_inset LatexCommand \index{methods. required}
955
956 \end_inset
957
958 required for model in ASCEND libraries
959 \begin_inset LatexCommand \label{tab:model2.addedReqdMethods}
960
961 \end_inset
962
963
964 \end_layout
965
966 \begin_layout Standard
967 \begin_inset Tabular
968 <lyxtabular version="3" rows="5" columns="2">
969 <features>
970 <column alignment="center" valignment="top" leftline="true" width="1.25in">
971 <column alignment="center" valignment="top" leftline="true" rightline="true" width="3.5in">
972 <row topline="true" bottomline="true">
973 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
974 \begin_inset Text
975
976 \begin_layout Standard
977 method
978 \end_layout
979
980 \end_inset
981 </cell>
982 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
983 \begin_inset Text
984
985 \begin_layout Standard
986 description
987 \end_layout
988
989 \end_inset
990 </cell>
991 </row>
992 <row topline="true">
993 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
994 \begin_inset Text
995
996 \begin_layout Standard
997
998 \family typewriter
999 default_self
1000 \begin_inset LatexCommand \index{default\_self}
1001
1002 \end_inset
1003
1004 , default_all
1005 \family default
1006
1007 \begin_inset LatexCommand \index{default\_all}
1008
1009 \end_inset
1010
1011
1012 \end_layout
1013
1014 \end_inset
1015 </cell>
1016 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none" width="3.5in">
1017 \begin_inset Text
1018
1019 \begin_layout Standard
1020
1021 \family roman
1022 \series medium
1023 \shape up
1024 \size normal
1025 \emph off
1026 \bar no
1027 \noun off
1028 \color none
1029 a method called automatically when any simulation is compiled to provide
1030 default values and adjust bounds for any variables which may have unsuitable
1031 defaults in their ATOM definitions.
1032 Usually the variables selected are those for which the model becomes ill-behave
1033 d if given poor initial guesses or bounds (e.g., zero).
1034 \end_layout
1035
1036 \end_inset
1037 </cell>
1038 </row>
1039 <row topline="true">
1040 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1041 \begin_inset Text
1042
1043 \begin_layout Standard
1044
1045 \family typewriter
1046 bound_self
1047 \begin_inset LatexCommand \index{bound\_self}
1048
1049 \end_inset
1050
1051 , bound_all
1052 \family default
1053
1054 \begin_inset LatexCommand \index{bound\_all}
1055
1056 \end_inset
1057
1058
1059 \end_layout
1060
1061 \end_inset
1062 </cell>
1063 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1064 \begin_inset Text
1065
1066 \begin_layout Standard
1067
1068 \family roman
1069 \series medium
1070 \shape up
1071 \size normal
1072 \emph off
1073 \bar no
1074 \noun off
1075 \color none
1076 a method to update the .
1077 upper_bound and .
1078 lower_bound value for each of the variables.
1079 ASCEND solvers use these bound values to help solve the model equations.
1080 \end_layout
1081
1082 \end_inset
1083 </cell>
1084 </row>
1085 <row topline="true">
1086 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1087 \begin_inset Text
1088
1089 \begin_layout Standard
1090
1091 \family typewriter
1092 scale_self
1093 \begin_inset LatexCommand \index{scale\_self}
1094
1095 \end_inset
1096
1097 , scale_all
1098 \family default
1099
1100 \begin_inset LatexCommand \index{scale\_all}
1101
1102 \end_inset
1103
1104
1105 \end_layout
1106
1107 \end_inset
1108 </cell>
1109 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1110 \begin_inset Text
1111
1112 \begin_layout Standard
1113
1114 \family roman
1115 \series medium
1116 \shape up
1117 \size normal
1118 \emph off
1119 \bar no
1120 \noun off
1121 \color none
1122 a method to update the .
1123 nominal value for each of the variables.
1124 ASCEND solvers will use these nominal values to rescale the variable to
1125 have a value of about one in magnitude to help solve the model equations.
1126 \end_layout
1127
1128 \end_inset
1129 </cell>
1130 </row>
1131 <row topline="true" bottomline="true">
1132 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1133 \begin_inset Text
1134
1135 \begin_layout Standard
1136
1137 \family typewriter
1138 check_self
1139 \begin_inset LatexCommand \index{check\_self}
1140
1141 \end_inset
1142
1143 , check_all
1144 \family default
1145
1146 \begin_inset LatexCommand \index{check\_all}
1147
1148 \end_inset
1149
1150
1151 \end_layout
1152
1153 \end_inset
1154 </cell>
1155 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1156 \begin_inset Text
1157
1158 \begin_layout Standard
1159
1160 \family roman
1161 \series medium
1162 \shape up
1163 \size normal
1164 \emph off
1165 \bar no
1166 \noun off
1167 \color none
1168 a method to check that the computations make sense.
1169 At first this method may be empty, but, with experience, one can add statements
1170 that detect answers that appear to be wrong.
1171 As ASCEND already does bounds checking, one should not check for going
1172 past bounds here.
1173 However, there could be a rule of thumb available that suggests one computed
1174 variable should be about an order of magnitude larger than another.
1175 This check could be done in this method.
1176 \end_layout
1177
1178 \end_inset
1179 </cell>
1180 </row>
1181 </lyxtabular>
1182
1183 \end_inset
1184
1185
1186 \end_layout
1187
1188 \end_inset
1189
1190
1191 \end_layout
1192
1193 \begin_layout Standard
1194 The
1195 \family typewriter
1196 bound_self
1197 \family default
1198 and
1199 \family typewriter
1200 scale_self
1201 \family default
1202 , methods we have written are both empty.
1203 We anticipate no difficulties with variable scaling or bounding for this
1204 small model.
1205 Larger models can often give difficult problems in solving if the variables
1206 in them are not properly scaled and bounded; these issues must be taken
1207 very seriously for such models.
1208 \end_layout
1209
1210 \begin_layout Standard
1211 We have included the variables that define the geometry of the vessel in
1212
1213 \family typewriter
1214 defaults_self
1215 \family default
1216 method to avoid such things as negative initial values for vessel_volume.
1217 The compiler for ASCEND runs this method as soon as the model is compiled
1218 into an instance so the variables mentioned here start with their default
1219 values.
1220 \end_layout
1221
1222 \begin_layout Standard
1223 Exit ASCEND and repeat all the steps above to edit, load and compile this
1224 new vessel type definition.
1225 Then proceed as follows.
1226 \end_layout
1227
1228 \begin_layout Itemize
1229 In the Browser window, examine the values for those variables mentioned
1230 in the default_self method.
1231 Note they already have their default values.
1232 \end_layout
1233
1234 \begin_layout Itemize
1235 To place the new instance v in a solvable state, go to the Browser window.
1236 Pick the command Run method under the Edit button.
1237 Select first the method values and hit OK.
1238 \end_layout
1239
1240 \begin_layout Itemize
1241 Repeat the last step but this time select the method reset.
1242
1243 \end_layout
1244
1245 \begin_layout Standard
1246 In the Browser, examine the values for the variables listed in the method
1247 values in Figure
1248 \begin_inset LatexCommand \ref{fig:model2.vesselWithMethods}
1249
1250 \end_inset
1251
1252
1253 \noun off
1254 .
1255 They should be set to those stated (remember you can alter the units ASCEND
1256 uses to report the values by using the tools in the Units window).Also examine
1257 the fixed flags for these variables; they should all be TRUE (remember
1258 that you can find which variables are fixed all at once by using the By
1259 type command under the Find button).
1260
1261 \end_layout
1262
1263 \begin_layout Itemize
1264 Finally export v to the Solver.
1265 The Eligible window should NOT appear; rather that Solver should report
1266 the model to be square.
1267
1268 \end_layout
1269
1270 \begin_layout Itemize
1271 Solve by selecting Solve under the Execute button.
1272 \end_layout
1273
1274 \begin_layout Standard
1275 The inclusion of methods has made the process of making this model much
1276 easier to get well-posed.
1277 This approach is the one that works for really large, complex models.
1278 \end_layout
1279
1280 \begin_layout Section
1281 Parameterizing the vessel model
1282 \begin_inset LatexCommand \label{sec:model2.parameterizingVessel}
1283
1284 \end_inset
1285
1286
1287 \end_layout
1288
1289 \begin_layout Standard
1290 Reuse generally implies creating a model which will have as a part an instance
1291 of a previously defined type.
1292 For example, let us compute metal_mass as a function of the H_to_D_ratio
1293 for a vessel for a fixed vessel_volume.
1294 We would like to see if there is a value for the H_to_D_ratio for which
1295 the metal_mass is minimum for a vessel with a given vessel_volume.
1296 We might wonder if metal_mass goes to infinity as this ratio goes either
1297 to zero or infinity.
1298 \end_layout
1299
1300 \begin_layout Subsection
1301 Creating a parameterized version of vessel
1302 \end_layout
1303
1304 \begin_layout Standard
1305 To use instances of our model as parts in another model, we can parameterize
1306 it.
1307 We use parameterization to tell a future user that the parameters are objects
1308 he or she is likely to share among many different parts of a model.
1309 We wish to create a table containing different values of
1310 \family typewriter
1311 H_to_D_ratio
1312 \family default
1313 vs.
1314
1315 \family typewriter
1316 metal_mass
1317 \family default
1318 .
1319 We can accomplish this by computing simultaneously several different vessels
1320 having the same
1321 \family typewriter
1322 vessel_volume
1323 \family default
1324 ,
1325 \family typewriter
1326 wall_thickness
1327 \family default
1328 and
1329 \family typewriter
1330 metal_density
1331 \family default
1332 .
1333 The objects we want to see and/or share for each instance of a vessel should
1334 include, therefore:
1335 \family typewriter
1336 H_to_D_ratio
1337 \family default
1338 ,
1339 \family typewriter
1340 metal_mass
1341 \family default
1342 ,
1343 \family typewriter
1344 metal_density
1345 \family default
1346 ,
1347 \family typewriter
1348 vessel_volume
1349 \family default
1350 and
1351 \family typewriter
1352 wall_thickness
1353 \family default
1354 .
1355 \end_layout
1356
1357 \begin_layout Standard
1358 The code in Figure
1359 \begin_inset LatexCommand \ref{fig:model2.parameterizedVessel}
1360
1361 \end_inset
1362
1363
1364 \noun off
1365 indicates the changes we make to the model declaration statement and the
1366 statements defining the variables to parameterize our model.
1367 \end_layout
1368
1369 \begin_layout Standard
1370 \begin_inset LatexCommand \label{fig:model2.parameterizedVessel}
1371
1372 \end_inset
1373
1374 The parameterized version of vessel model (
1375 \begin_inset LatexCommand \index{1014608}
1376
1377 \end_inset
1378
1379 vesselParams.a4c)
1380 \end_layout
1381
1382 \begin_layout Standard
1383 \begin_inset ERT
1384 status open
1385
1386 \begin_layout Standard
1387
1388
1389 \backslash
1390 lstset{language=ASCEND}
1391 \end_layout
1392
1393 \begin_layout Standard
1394
1395
1396 \backslash
1397 lstinputlisting[firstline=24]{../models/vesselParams.a4c}
1398 \end_layout
1399
1400 \end_inset
1401
1402
1403 \end_layout
1404
1405 \begin_layout Standard
1406 Substitute the statements in Figure
1407 \begin_inset LatexCommand \ref{fig:model2.parameterizedVessel}
1408
1409 \end_inset
1410
1411
1412 \noun off
1413 for lines 2 through 9 in
1414 \noun default
1415 Figure
1416 \noun off
1417
1418 \begin_inset LatexCommand \ref{fig:model2.vesselWithMethods}
1419
1420 \end_inset
1421
1422 .
1423 Save the result in the file vesselParam.a4c.
1424 \end_layout
1425
1426 \begin_layout Standard
1427 Note the use of the
1428 \begin_inset LatexCommand \index{1014610}
1429
1430 \end_inset
1431
1432
1433 \begin_inset LatexCommand \index{1014609}
1434
1435 \end_inset
1436
1437
1438 \family typewriter
1439 WILL_BE
1440 \family default
1441 statement in the parameter list.
1442 By declaring that the type of a parameter will be compatible with the types
1443 shown, the compiler can tell immediately if a user of this model is passing
1444 the wrong type of object when defining an instance of a vessel.
1445 \end_layout
1446
1447 \begin_layout Subsection
1448 Using the parameterized vessel model
1449 \end_layout
1450
1451 \begin_layout Standard
1452 A type definition will set up our
1453 \begin_inset LatexCommand \index{1014611}
1454
1455 \end_inset
1456
1457 table of H_to_D_ratio values vs.
1458 metal_mass so we can observe approximately where it attains a minimum value.
1459 ASCEND allows us to create arrays of instances of any type.
1460 Here we shall create an array of vessels.
1461 The type definition is shown in Figure
1462 \begin_inset LatexCommand \ref{fig:model2.tabulatedVessel}
1463
1464 \end_inset
1465
1466
1467 \noun off
1468 .
1469 Note that the line numbers are not a part of the actual code.
1470 We include them here only so we can reference them as needed later.
1471 \end_layout
1472
1473 \begin_layout Standard
1474 tabulated_vessel_values model
1475 \begin_inset LatexCommand \label{fig:model2.tabulatedVessel}
1476
1477 \end_inset
1478
1479
1480 \end_layout
1481
1482 \begin_layout Standard
1483 \begin_inset ERT
1484 status open
1485
1486 \begin_layout Standard
1487
1488
1489 \backslash
1490 lstset{language=ASCEND}
1491 \end_layout
1492
1493 \begin_layout Standard
1494
1495
1496 \backslash
1497 lstinputlisting[firstline=26]{../models/vesselTabulated.a4c}
1498 \end_layout
1499
1500 \end_inset
1501
1502
1503 \end_layout
1504
1505 \begin_layout Standard
1506 Add this model to the end of the file
1507 \family typewriter
1508 vesselParam.a4c
1509 \family default
1510
1511 \begin_inset LatexCommand \index{vesselTabulated.a4c}
1512
1513 \end_inset
1514
1515 (after the vessel model) and save the file as
1516 \family typewriter
1517 vesselTabulated.a4c
1518 \family default
1519 .
1520 Compile an instance of
1521 \family typewriter
1522 tabulated_vessel_values
1523 \family default
1524 (call it
1525 \family typewriter
1526 tvv
1527 \family default
1528 ), run the values and specify methods for it, and then solve it.
1529 You will discover that the tenth element of the
1530 \family typewriter
1531 metal_mass
1532 \family default
1533 array, corresponding to an
1534 \family typewriter
1535 H_to_D_ratio
1536 \family default
1537 of 1 has the minimum value of 510.257 kilograms.
1538 \end_layout
1539
1540 \begin_layout Section
1541 Creating a script
1542 \begin_inset LatexCommand \index{script, creating}
1543
1544 \end_inset
1545
1546 to demonstrate this model
1547 \begin_inset LatexCommand \label{sec:model2.creatingScript}
1548
1549 \end_inset
1550
1551
1552 \end_layout
1553
1554 \begin_layout Standard
1555 The last step to make the model reusable is to create a script that anyone
1556 can easily run.
1557 Running the model successfully will allow a user to demonstrate the use
1558 of the model and to explore an instance it by browsing it.
1559 \end_layout
1560
1561 \begin_layout Standard
1562 ASCEND allows one to create such a script using either an editor or the
1563 tools in the
1564 \series bold
1565 Script
1566 \series default
1567 window.
1568 \end_layout
1569
1570 \begin_layout Standard
1571 Restart the ASCEND system.
1572 You will have three windows open plus the large one which disappears by
1573 itself in a few seconds: the
1574 \series bold
1575 Script
1576 \series default
1577 , the
1578 \series bold
1579 Library
1580 \series default
1581 and the
1582 \series bold
1583 Console
1584 \series default
1585 windows.
1586 \end_layout
1587
1588 \begin_layout Standard
1589 In the
1590 \series bold
1591 Script
1592 \series default
1593 window you will see the license agreement information for ASCEND.
1594 First clear the license agreement
1595 \begin_inset LatexCommand \index{license agreement}
1596
1597 \end_inset
1598
1599 from this window by doing the following two steps:
1600 \end_layout
1601
1602 \begin_layout Itemize
1603 Click
1604 \series bold
1605 Select all
1606 \series default
1607 under the Edit menu.
1608
1609 \end_layout
1610
1611 \begin_layout Itemize
1612 Then click
1613 \series bold
1614 Delete statements
1615 \series default
1616 under the same button.
1617
1618 \end_layout
1619
1620 \begin_layout Standard
1621 With the
1622 \series bold
1623 Script
1624 \series default
1625 window
1626 \series bold
1627
1628 \series default
1629 now cleared of text, select
1630 \series bold
1631 Record actions
1632 \series default
1633 under the Edit menu to start recording the steps you are about to undertake.
1634 Then,
1635 \end_layout
1636
1637 \begin_layout Itemize
1638 In the
1639 \series bold
1640 Library
1641 \series default
1642 window, under the Edit menu, select
1643 \series bold
1644 Delete all types
1645 \series default
1646 .
1647 Hit
1648 \series bold
1649 Delete all
1650 \series default
1651 on the small window that appears.
1652 \end_layout
1653
1654 \begin_layout Itemize
1655 Load the file
1656 \family typewriter
1657 vesselTabulated.a4c
1658 \family default
1659 , the file containing the model called
1660 \family typewriter
1661 tabulated_vessel_values
1662 \family default
1663 .
1664 Do this by selecting the Read types from file tool under the File menu
1665 and browsing the file system to find it.
1666 If you have trouble finding it, be sure to set the
1667 \series bold
1668 Files of type
1669 \series default
1670 dropdown at the bottom of the file browsing window to allow all types of
1671 files to be seen.
1672 \end_layout
1673
1674 \begin_layout Itemize
1675 Select the type
1676 \family typewriter
1677 tabulated_vessel_value
1678 \family default
1679 s in the right
1680 \series bold
1681 Library
1682 \series default
1683 window and compile an instance of it by selecting
1684 \series bold
1685 Create simulation
1686 \series default
1687 under the Edit menu.
1688 In the small window that appears, enter the name
1689 \family typewriter
1690 tvv
1691 \family default
1692 and hit OK.
1693 \end_layout
1694
1695 \begin_layout Itemize
1696 Export the instance to the
1697 \series bold
1698 Browser
1699 \series default
1700 by selecting
1701 \series bold
1702 Simulation to Browser
1703 \series default
1704 under the Export menu.
1705 \end_layout
1706
1707 \begin_layout Itemize
1708 Initialize the variable values by running the
1709 \family typewriter
1710 values
1711 \family default
1712 method.
1713 Do this by selecting
1714 \series bold
1715 Run method
1716 \series default
1717 under the Edit menu.
1718 Select the
1719 \family typewriter
1720 values
1721 \family default
1722 method and hit
1723 \series bold
1724 OK
1725 \series default
1726 .
1727 \end_layout
1728
1729 \begin_layout Itemize
1730 Set the
1731 \family typewriter
1732 fixed
1733 \family default
1734 flags to get a well-posed problem by repeating the last step but this time
1735 select the
1736 \family typewriter
1737 reset
1738 \family default
1739 method.
1740 \end_layout
1741
1742 \begin_layout Itemize
1743 Export the instance
1744 \family typewriter
1745 tvv
1746 \family default
1747 to the Solver by selecting
1748 \series bold
1749 to Solver
1750 \series default
1751 under the Export menu.
1752 \end_layout
1753
1754 \begin_layout Itemize
1755 Solve
1756 \family typewriter
1757 tvv
1758 \family default
1759 by selecting
1760 \series bold
1761 Solve
1762 \series default
1763 under the Execute menu in the
1764 \series bold
1765 Solver
1766 \series default
1767 window.
1768 \end_layout
1769
1770 \begin_layout Itemize
1771 Return to the
1772 \series bold
1773 Script
1774 \series default
1775 window and turn off the recording by deselecting the
1776 \series bold
1777 Record actions
1778 \series default
1779 option under the Edit menu.
1780 \end_layout
1781
1782 \begin_layout Itemize
1783 Save the script you have just created by selecting
1784 \series bold
1785 Save
1786 \series default
1787 under the File menu of the
1788 \series bold
1789 Script
1790 \series default
1791 window.
1792 Name the file
1793 \family typewriter
1794 vesselTabulated.a4s
1795 \family default
1796 (note the 's' ending) to indicate it is a script file corresponding to
1797 the model file
1798 \family typewriter
1799 vesselTabulated.a4c
1800 \family default
1801 (note the 'c' ending) file.
1802 \end_layout
1803
1804 \begin_layout Itemize
1805 Exit by selecting
1806 \series bold
1807 Exit ASCEND
1808 \series default
1809 under the File menu on the
1810 \series bold
1811 Script
1812 \series default
1813 window.
1814 The contents of the
1815 \series bold
1816 Script
1817 \series default
1818 window at this point will be similar to that in Figure
1819 \begin_inset LatexCommand \ref{fig:model2.scriptVesselTabulated}
1820
1821 \end_inset
1822
1823
1824 \noun off
1825 (although the path to the file may differ).
1826 \end_layout
1827
1828 \begin_layout Itemize
1829 Restart ASCEND.
1830 \end_layout
1831
1832 \begin_layout Itemize
1833 Open the script you just created by selecting
1834 \series bold
1835 Read file
1836 \series default
1837 under the File menu on the
1838 \series bold
1839 Script
1840 \series default
1841 window.
1842 (Be sure you are allowing the system to see files with the ending
1843 \family typewriter
1844 .a4s
1845 \family default
1846 by using the
1847 \series bold
1848 Files of type
1849 \series default
1850 dropdown at the bottom of the file-browsing window.)
1851 \end_layout
1852
1853 \begin_layout Itemize
1854 Highlight all the instructions in this script and then execute the highlighted
1855 instructions by selecting
1856 \series bold
1857 Statements selected
1858 \series default
1859 under the
1860 \series bold
1861 Execute
1862 \series default
1863 menu.
1864 \end_layout
1865
1866 \begin_layout Standard
1867 You will run the same sequence of instructions you ran to create the script.
1868 \end_layout
1869
1870 \begin_layout Standard
1871 \begin_inset LatexCommand \label{fig:model2.scriptVesselTabulated}
1872
1873 \end_inset
1874
1875 Script to run
1876 \family typewriter
1877 vesselTabulated.a4c
1878 \family default
1879 (this is the contents of the file
1880 \family typewriter
1881 vesselTabulated.a4s
1882 \family default
1883
1884 \begin_inset LatexCommand \index{vesselTabultated.a4s}
1885
1886 \end_inset
1887
1888 )
1889 \end_layout
1890
1891 \begin_layout Standard
1892 \begin_inset ERT
1893 status open
1894
1895 \begin_layout Standard
1896
1897
1898 \backslash
1899 lstinputlisting[firstline=29]{../models/vesselTabulated.a4s}
1900 \end_layout
1901
1902 \end_inset
1903
1904
1905 \end_layout
1906
1907 \begin_layout Section
1908 Discussion
1909 \end_layout
1910
1911 \begin_layout Standard
1912 In this chapter we converted the vessel model into a form where you and
1913 others in the future will have a chance to reuse it.
1914 We did this by first adding methods to make the problem well-posed and
1915 to provide values for the fixed variables for which we readily found a
1916 solution when playing with our original model as we did in the previous
1917 chapter.
1918 We then thought of a typical use for this model and developed a parameterized
1919 version based on that use.
1920 If this model were in a library, a future user of it would most often simply
1921 have to understand the parameters to create an instance of this type of
1922 model.
1923 We next added
1924 \family typewriter
1925 NOTES
1926 \family default
1927 , a form of active comments, to the model.
1928 We suggest that notes are much more useful than comments as we can provide
1929 tools that can extract them and allow us to search them, for example, to
1930 find a model with a given functionality.
1931 Finally, we showed you how to create a script by turning on a "phone" session
1932 where ASCEND records the actions one takes when loading, compiling and
1933 solving a model.
1934 One can save and play this script in the future to see a typical use of
1935 the model.
1936 \end_layout
1937
1938 \begin_layout Standard
1939 In the next chapter, we look at how we can plot the results we created in
1940 the model
1941 \family typewriter
1942 vesselTabulated.a4c
1943 \family default
1944 .
1945 We will have to reuse a model someone else has put into the library of
1946 available models.
1947 In other words, the "shoe is on the other foot," and we quickly experience
1948 the difficulties with reuse first hand.
1949 We will also learn how to run a case study from which we can extract the
1950 same information with a single vessel model run multiple times.
1951 \end_layout
1952
1953 \end_body
1954 \end_document

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