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

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 530 531 532 533 534 535 \begin_inset Text 536 537 \begin_layout Standard 538 539 \end_layout 540 541 \end_inset 542 543 544 \begin_inset Text 545 546 \begin_layout Standard 547 548 \end_layout 549 550 \end_inset 551 552 553 554 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 572 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 584 585 586 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 604 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 626 627 628 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 646 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 669 670 671 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 689 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 712 713 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 969 970 971 972 973 974 \begin_inset Text 975 976 \begin_layout Standard 977 method 978 \end_layout 979 980 \end_inset 981 982 983 \begin_inset Text 984 985 \begin_layout Standard 986 description 987 \end_layout 988 989 \end_inset 990 991 992 993 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 1016 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 1038 1039 1040 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 1063 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 1084 1085 1086 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 1109 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 1130 1131 1132 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 1155 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 1180 1181 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