# Annotation of /trunk/doc/howto-methods.lyx

Increased max ext relations to 50.

 1 johnpye 825 #LyX 1.4.1 created this file. For more info see http://www.lyx.org/ 2 \lyxformat 245 3 \begin_document 4 \begin_header 5 \textclass book 6 \language english 7 \inputencoding auto 8 \fontscheme default 9 \graphics default 10 \paperfontsize default 11 \spacing single 12 \papersize a4paper 13 \use_geometry false 14 \use_amsmath 2 15 \cite_engine basic 16 \use_bibtopic false 17 \paperorientation portrait 18 \secnumdepth 3 19 \tocdepth 3 20 \paragraph_separation indent 21 \defskip medskip 22 \quotes_language english 23 \papercolumns 1 24 \papersides 2 25 \paperpagestyle default 26 \tracking_changes false 27 \output_changes true 28 \end_header 29 30 \begin_body 31 32 \begin_layout Chapter 33 Writing METHODs 34 \begin_inset LatexCommand \label{cha:methods} 35 36 \end_inset 37 38 39 \end_layout 40 41 \begin_layout Standard 42 In this chapter we describe a methodology (pun intended) which can help 43 make anyone who can solve a quadratic equation a mathematical modeling 44 expert. 45 This methodology helps you to avoid mistakes and to find mistakes quickly 46 when you make them. 47 Finding bugs weeks after creating a model is annoying, inefficient, and 48 (frequently) embarrassing. 49 Because METHOD code can be large, we do not include many examples here. 50 51 \begin_inset Note Note 52 status collapsed 53 54 \begin_layout Standard 55 See ***vessel something*** for detailed examples 56 \end_layout 57 58 \end_inset 59 60 One of the advantages of this methodology is that it allows almost automatic 61 \begin_inset LatexCommand \index{methods, automatic generation} 62 63 \end_inset 64 65 generation of methods for a model based on the declarative structure (defined 66 parts and variables) in the model, as we shall see in Section\InsetSpace ~ 67 68 \begin_inset LatexCommand \ref{sec:methods.automation} 69 70 \end_inset 71 72 73 \noun off 74 . 75 Even if you skip much of this chapter, read 76 \noun default 77 Section\InsetSpace ~ 78 79 \noun off 80 81 \begin_inset LatexCommand \ref{sec:methods.automation} 82 83 \end_inset 84 85 86 \end_layout 87 88 \begin_layout Standard 89 We divide methods into 90 \family typewriter 91 _self 92 \family default 93 and 94 \family typewriter 95 _all 96 \family default 97 categories. 98 The premise of our approach to design methods is that we can write the 99 100 \family typewriter 101 _self 102 \family default 103 methods incrementally, building on the already tested methods of previous 104 MODEL parts we are reusing. 105 In this way we never have to write a single huge method that directly manipulat 106 es the hundreds of variables that are in the model hierarchy. 107 Were that all there was to it, things would actually be pretty simple. 108 However, in ASCEND, one can also select to solve any part of an ASCEND 109 model (in particular, any part that is an instance of a single type), and 110 this capability complicates method writing - but not by much if we really 111 understand the approach we advocate here. 112 As an example, suppose we have a flowsheet that has a reactor followed 113 by a flash unit in it. 114 In ASCEND, we can select to solve the entire flowsheet, only the reactor, 115 only the flash unit or even any one of the streams in it (yes, each stream 116 has physical property calculations that belong to it making it interesting 117 to isolate and solve). 118 Should we choose to solve only the flash unit, ASCEND will isolate the 119 equations defining the flash - including the equations we use when defining 120 the input and output streams to it as they are a part of the flash unit. 121 But the input to the flash is also the output from the reactor and is a 122 part of the reactor, too. 123 Each part would typically take the prime responsibility for supplying methods 124 that will set fix flags, set nominal values, etc., for its variables, but 125 who owns the variables they both share such as in the connecting stream? 126 By 127 \begin_inset Quotes eld 128 \end_inset 129 130 tradition 131 \begin_inset Quotes erd 132 \end_inset 133 134 in chemical engineering flowsheet modeling, we will assert that the reactor 135 has prime responsibility for its output stream. 136 If we are solving the entire flowsheet, it should set the flags, etc., for 137 its output stream. 138 However, when we isolate the flash for solving, the flash unit must assume 139 responsibility to set fix flags, nominal values, etc., for the output stream 140 from the reactor as that stream is its input stream. 141 The 142 \family typewriter 143 _all 144 \family default 145 methods allow us to handle these shared variables correctly when we isolate 146 a part for solving by itself. 147 \begin_inset Note Note 148 status collapsed 149 150 \begin_layout Standard 151 This needs more explanation: I don't find it completely clear. 152 \end_layout 153 154 \end_inset 155 156 157 \end_layout 158 159 \begin_layout Standard 160 Usually discovery of the information you need to write the methods proceeds 161 in the order that they appear below: 162 \family typewriter 163 check 164 \family default 165 , 166 \family typewriter 167 default 168 \family default 169 , 170 \family typewriter 171 specify 172 \family default 173 , 174 \family typewriter 175 bound 176 \family default 177 , 178 \family typewriter 179 scale 180 \family default 181 . 182 183 \end_layout 184 185 \begin_layout Section 186 Why use standardised methods on models? 187 \end_layout 188 189 \begin_layout Standard 190 In the present chapter, we are proposing that you use a particular standardised 191 set of methods on your models. 192 While ASCEND doesn't force you to follow these conventions, we hope that 193 you will 194 \emph on 195 choose 196 \emph default 197 to follow them, because: 198 \end_layout 199 200 \begin_layout Itemize 201 You models will be more portable. 202 \end_layout 203 204 \begin_layout Itemize 205 They will integrate better with the existing model library when composing 206 larger models composed of smaller perhaps pre-existing models. 207 \end_layout 208 209 \begin_layout Itemize 210 Other users will be be more easily able to understand what you have built. 211 \end_layout 212 213 \begin_layout Itemize 214 The proposed structure has, in our experience, made for models that are 215 easier to debug. 216 \end_layout 217 218 \begin_layout Standard 219 There will be cases where these standard methods don't suffice for your 220 needs; these are just proposals for a useful starting point and shared-use 221 conventions. 222 \end_layout 223 224 \begin_layout Standard 225 Note that if you do not write the standard methods, your MODEL will inherit 226 the ones given in the library 227 \family typewriter 228 basemodel.a4l 229 \family default 230 . 231 The 232 \family typewriter 233 ClearAll 234 \family default 235 and 236 \family typewriter 237 reset 238 \family default 239 methods here will work for you if you follow the guidelines for the method 240 241 \family typewriter 242 specify 243 \family default 244 . 245 The other methods defined in 246 \family typewriter 247 basemodel.a4l 248 \family default 249 250 \family typewriter 251 (check_self 252 \family default 253 , 254 \family typewriter 255 default_self 256 \family default 257 , 258 \family typewriter 259 bound_self 260 \family default 261 , 262 \family typewriter 263 scale_self 264 \family default 265 , 266 \family typewriter 267 check_all 268 \family default 269 , 270 \family typewriter 271 default_all 272 \family default 273 , 274 \family typewriter 275 bound_all 276 \family default 277 , 278 \family typewriter 279 scale_all 280 \family default 281 ) all contain 282 \family typewriter 283 STOP 284 \family default 285 statements that will warn you that you have skipped something important, 286 should you accidentally call one of these methods. 287 If you create a model for someone else and they run into one of these 288 \family typewriter 289 STOP 290 \family default 291 errors while using your model, that error is your fault. 292 \end_layout 293 294 \begin_layout Section 295 Methods *_self 296 \begin_inset LatexCommand \index{methods, \_self} 297 298 \end_inset 299 300 VS *_all 301 \begin_inset LatexCommand \index{methods, \_all} 302 303 \end_inset 304 305 306 \end_layout 307 308 \begin_layout Standard 309 When you create a model definition, you create a container holding variables, 310 equations, arrays, and other models. 311 You create methods in the same definition to control the state of (the 312 values stored in) all these parts. 313 ASCEND lets you share objects among several models by passing objects through 314 a model interface (the 315 \family typewriter 316 MODEL 317 \family default 318 parameter list), by creating ALIASES 319 \begin_inset LatexCommand \index{ALIASES} 320 321 \end_inset 322 323 for parts within contained objects, and even by merging parts (though merging 324 should be avoided for any object larger than a variable). 325 326 \end_layout 327 328 \begin_layout Standard 329 \begin_inset Marginal 330 status collapsed 331 332 \begin_layout Standard 333 Too many cooks 334 \begin_inset LatexCommand \index{cooks} 335 336 \end_inset 337 338 spoil the broth 339 \begin_inset LatexCommand \index{broth} 340 341 \end_inset 342 343 . 344 \end_layout 345 346 \end_inset 347 348 The problem this creates for you as a 349 \family typewriter 350 METHOD 351 \family default 352 writer is to decide which of the several 353 \family typewriter 354 MODEL 355 \family default 356 s that share an object is responsible for updating that variable's default, 357 bounds, and nominal values. 358 You could decide that every model which shares a variable is responsible 359 for these values. 360 This decision will lead to many, many, many hard to understand conflicts 361 as different models all try to manage the same value. 362 And, the last one run will in fact have the final say. 363 But it is difficult to know always which is the last one run. 364 The sensible approach is to make only one model responsible for the bounding, 365 scaling, and default setting of each variable: 366 \emph on 367 the model that creates the variable in the first place 368 \emph default 369 . 370 If you abide by this approach, you will keep things much simpler for yourself. 371 And, fortunately, the modeling language makes it pretty clear who has created 372 each and every variable - except when merging variables. 373 \end_layout 374 375 \begin_layout Standard 376 \begin_inset Marginal 377 status collapsed 378 379 \begin_layout Standard 380 Use *_self methods on locally created variables and parts 381 \end_layout 382 383 \end_inset 384 385 Consider the following model and creating the 386 \family typewriter 387 *_self 388 \family default 389 methods 390 \family typewriter 391 default_self 392 \family default 393 , 394 \family typewriter 395 check_self 396 \family default 397 , 398 \family typewriter 399 bound_self 400 \family default 401 , and 402 \family typewriter 403 scale_self 404 \family default 405 for it. 406 407 \end_layout 408 409 \begin_layout LyX-Code 410 MODEL selfish( 411 \end_layout 412 413 \begin_layout LyX-Code 414 external_var WILL_BE solver_var; 415 \end_layout 416 417 \begin_layout LyX-Code 418 out_thingy WILL_BE input_part; 419 \end_layout 420 421 \begin_layout LyX-Code 422 ); 423 \end_layout 424 425 \begin_layout LyX-Code 426 my_variable IS_A solver_var; 427 \end_layout 428 429 \begin_layout LyX-Code 430 431 \end_layout 432 433 \begin_layout LyX-Code 434 peek_at_variable ALIASES out_thingy.mabob.cost; 435 \end_layout 436 437 \begin_layout LyX-Code 438 my_thingy IS_A nother_part; 439 \end_layout 440 441 \begin_layout LyX-Code 442 navel_gaze ALIASES my_thingy.mabob.cost; 443 \end_layout 444 445 \begin_layout LyX-Code 446 END selfish; 447 \end_layout 448 449 \begin_layout Standard 450 451 \end_layout 452 453 \begin_layout Standard 454 455 \family typewriter 456 IS_A 457 \family default 458 statements indicate all the parts we have created in this model: namely, 459 the 460 \family typewriter 461 solver_var 462 \family default 463 we call 464 \family typewriter 465 my_variable 466 \family default 467 and the 468 \family typewriter 469 nother_part 470 \family default 471 we call 472 \family typewriter 473 my_thingy 474 \family default 475 . 476 This model should manage the value of the only variable it creates: 477 \family typewriter 478 my_variable 479 \family default 480 . 481 The variable, 482 \family typewriter 483 external_var 484 \family default 485 , comes in from the outside so some other model has created it and should 486 manage it. 487 The variables 488 \family typewriter 489 peek_at_variable 490 \family default 491 and 492 \family typewriter 493 navel_gaze 494 \family default 495 also are not created here and should not be managed in the 496 \family typewriter 497 *_self 498 \family default 499 methods of 500 \family typewriter 501 selfish 502 \family default 503 . 504 505 \family typewriter 506 my_thingy.mabob.cost 507 \family default 508 belongs to a part we created. 509 We want to default, bound, or scale variables in all parts we create, also, 510 so we must call 511 \family typewriter 512 my_thingy.default_self 513 \family default 514 whenever 515 \family typewriter 516 default_self 517 \family default 518 is called for this model. 519 Its 520 \family typewriter 521 *_self 522 \family default 523 method should in turn call the 524 \family typewriter 525 *_self 526 \family default 527 method for 528 \family typewriter 529 mabob 530 \family default 531 , which should set defaults, bounds and scaling for its variable, 532 \family typewriter 533 cost 534 \family default 535 . 536 Finally, 537 \family typewriter 538 out_thingy 539 \family default 540 is an input parameter and is not created here; we should not call 541 \family typewriter 542 out_thingy.default_self 543 \family default 544 , therefore, as some other model will do so. 545 \end_layout 546 547 \begin_layout Standard 548 \begin_inset Marginal 549 status collapsed 550 551 \begin_layout Standard 552 Use *_all methods to manage a troublesome part 553 \end_layout 554 555 \end_inset 556 557 As noted above, you may choose to isolate any mathematical subproblem in 558 a large simulation for debugging or solving purposes. 559 When you do this isolation using the Browser and Solver tools, you still 560 need to call scaling, bounding, and checking methods for all parts of the 561 isolated subproblem, even for those parts that come in from the outside. 562 This is easily done by writing 563 \family typewriter 564 *_all 565 \family default 566 methods. 567 In the example above, 568 \family typewriter 569 scale_all 570 \family default 571 will scale 572 \family typewriter 573 external_var 574 \family default 575 and call 576 \family typewriter 577 out_thingy.scale_all 578 \family default 579 because these parts are defined using 580 \family typewriter 581 WILL_BE 582 \family default 583 584 \begin_inset LatexCommand \index{WILL\_BE} 585 586 \end_inset 587 588 statements. 589 Finally 590 \family typewriter 591 scale_all 592 \family default 593 will call its local 594 \family typewriter 595 *_self 596 \family default 597 to do all the normal scaling. 598 \end_layout 599 600 \begin_layout Standard 601 That's the big picture of 602 \family typewriter 603 *_self 604 \family default 605 and 606 \family typewriter 607 *_all 608 \family default 609 methods. 610 Each kind of method (bound, scale, default, check) has its own peculiarities, 611 which we cover in Section 612 \begin_inset LatexCommand \ref{sec:methods.selfMethods} 613 614 \end_inset 615 616 617 \noun off 618 and 619 \noun default 620 Section 621 \noun off 622 623 \begin_inset LatexCommand \ref{sec:methods.allMethods} 624 625 \end_inset 626 627 , but they all follow the rules above 628 \noun default 629 and 630 \noun off 631 distinguish among variables and parts defined with 632 \family typewriter 633 \noun default 634 WILL_BE 635 \family default 636 \noun off 637 (managed in * 638 \family typewriter 639 \noun default 640 _all 641 \family default 642 \noun off 643 only), IS_A 644 \begin_inset LatexCommand \index{IS\_A} 645 646 \end_inset 647 648 (managed in 649 \family typewriter 650 \noun default 651 *_self 652 \family default 653 \noun off 654 only), and 655 \family typewriter 656 \noun default 657 ALIASES 658 \family default 659 \noun off 660 (not our responsibility). 661 \end_layout 662 663 \begin_layout Section 664 How to write ClearAll 665 \begin_inset LatexCommand \index{ClearAll} 666 667 \end_inset 668 669 and reset 670 \begin_inset LatexCommand \index{reset} 671 672 \end_inset 673 674 675 \end_layout 676 677 \begin_layout Standard 678 Writing these two standard methods in your model is very simple: do nothing. 679 You may wish to write alternative 680 \family typewriter 681 reset_* 682 \family default 683 methods as we shall discuss. 684 All models inherit these methods from the definitions in 685 \family typewriter 686 basemodel.a4l 687 \family default 688 . 689 Just so you know, here is what they do. 690 \end_layout 691 692 \begin_layout Subsection 693 694 \family typewriter 695 METHOD ClearAll 696 \end_layout 697 698 \begin_layout Standard 699 This method finds any variable that is a 700 \family typewriter 701 solver_var 702 \family default 703 or refinement of 704 \family typewriter 705 solver_var 706 \family default 707 and changes the 708 \family typewriter 709 .fixed 710 \family default 711 flag on that var to 712 \family typewriter 713 FALSE 714 \family default 715 . 716 This method only touches the 717 \family typewriter 718 .fixe 719 \family default 720 d flags; i.e., it does not change the value of 721 \family typewriter 722 .included 723 \family default 724 flags on relations or return boolean, integer and symbol variables to a 725 default value. 726 727 \end_layout 728 729 \begin_layout Subsection 730 731 \family typewriter 732 METHOD reset 733 \end_layout 734 735 \begin_layout Standard 736 This method calls 737 \family typewriter 738 ClearAll 739 \family default 740 to bring the model to a standard state with all variables unfixed (free), 741 then it calls the user-written specify method to bring the model to a state 742 where it has an equal number of variables to calculate and equations to 743 solve - i.e., to being 744 \begin_inset Quotes eld 745 \end_inset 746 747 square. 748 \begin_inset Quotes erd 749 \end_inset 750 751 Normally you do not need to write this method: your models will inherit 752 this one unless you override it (redefine it) in your model. 753 \end_layout 754 755 \begin_layout Standard 756 This standard state is not necessarily the most useful starting state for 757 any particular application. 758 This method merely establishes a base case the modeler finds to be a good 759 starting point. 760 As an example, the modeler may elect to set fix variables for the base 761 case for a flash unit so it corresponds to an isothermal flash calculation. 762 Chemical engineers understand this case and can make changes from it to 763 set up other cases, such as an adiabatic flash, relatively easily by setting 764 and resetting but one or two 765 \family typewriter 766 .fixed 767 \family default 768 flags. 769 There is no one perfect "reset"' for all purposes. 770 Other 771 \family typewriter 772 reset_* 773 \family default 774 methods can also be written for particular purposes, if such arise 775 \begin_inset Foot 776 status collapsed 777 778 \begin_layout Standard 779 The name of a method, for example 780 \family typewriter 781 reset_someOtherPurpose 782 \family default 783 is a communication tool. 784 Please use meaningful names as long as necessary to tell what the method 785 does. 786 Avoid cryptic abbreviations and hyper-specialized jargon known only to 787 you and your three friends when you are naming methods; however, do not 788 shy away from technical terms common to the engineering domain in which 789 you are modeling. 790 \end_layout 791 792 \end_inset 793 794 . 795 \end_layout 796 797 \begin_layout Section 798 The 799 \family typewriter 800 *_self 801 \family default 802 803 \begin_inset LatexCommand \index{\_self} 804 805 \end_inset 806 807 methods 808 \begin_inset LatexCommand \label{sec:methods.selfMethods} 809 810 \end_inset 811 812 813 \end_layout 814 815 \begin_layout Standard 816 The following methods should be redefined by each reusable library 817 \family typewriter 818 MODEL 819 \family default 820 . 821 Models that do not supply proper versions of these methods are usually 822 very hard to reuse. 823 824 \end_layout 825 826 \begin_layout Subsection 827 828 \family typewriter 829 METHOD check_self 830 \family default 831 832 \begin_inset LatexCommand \index{check\_self} 833 834 \end_inset 835 836 837 \end_layout 838 839 \begin_layout Standard 840 One can benefit by writing this method first, though it is run last. 841 Just as they taught you in elementary school, always check your work. 842 Start by defining criteria for a successful solution that will not be included 843 in the equations solved and compute them in this method. 844 As you develop your 845 \family typewriter 846 MODEL 847 \family default 848 , you should expect to revise the check method from time to time, if you 849 are learning anything about the model. 850 We frequently change our definition of success when modeling. 851 \end_layout 852 853 \begin_layout Standard 854 When a mathematical model is solved, the assumptions that went into writing 855 (deriving) the equations should be checked. 856 Usually there are redundant equations available (more than one way to state 857 the physics or economics mathematically). 858 These should be used to check the particularly tricky bits of the model. 859 \end_layout 860 861 \begin_layout Standard 862 Check that the physical or intuitive (qualitative) relationships among variables 863 you expect to hold are true, especially if you have not written such relationsh 864 ips in terms of inequalities ( 865 \family typewriter 866 x*z <= y 867 \family default 868 ) in the 869 \family typewriter 870 MODEL 871 \family default 872 equations. 873 \end_layout 874 875 \begin_layout Standard 876 In some models, checking the variable values against absolute physical limits 877 ( 878 \family typewriter 879 temperature > 0{K} 880 \family default 881 and 882 \family typewriter 883 temperature < Tcritical 884 \family default 885 , for example) may be all that is necessary or possible. 886 Do not check variable values against their 887 \family typewriter 888 .lower_bound 889 \family default 890 or 891 \family typewriter 892 .upper_bound 893 \family default 894 , as ASCEND will do this for you. 895 \end_layout 896 897 \begin_layout Standard 898 If a check fails, use a 899 \family typewriter 900 STOP 901 \family default 902 903 \begin_inset LatexCommand \index{STOP} 904 905 \end_inset 906 907 statement to notify yourself (or your end-user) that the solution may be 908 bogus. 909 910 \family typewriter 911 STOP 912 \family default 913 raises an error signal and issues an error message. 914 915 \family typewriter 916 STOP 917 \family default 918 normally also stops further execution of the method and returns control 919 to a higher level, though there are interactive tools to force method execution 920 to continue. 921 922 \family typewriter 923 STOP 924 \family default 925 does not cause ASCEND to exit though: just for the method execution to 926 halt and for control to return to the user. 927 \end_layout 928 929 \begin_layout Subsection 930 931 \family typewriter 932 METHOD default_self 933 \begin_inset LatexCommand \index{default\_self} 934 935 \end_inset 936 937 938 \end_layout 939 940 \begin_layout Standard 941 This method should set default values for any variables declared locally 942 ( 943 \family typewriter 944 IS_A 945 \family default 946 ) to the model. 947 If the default value declared for the atom type, of which the variable 948 is an instance, is appropriate (and typically it is), then you need not 949 set a specific default value here. 950 This method also should run 951 \family typewriter 952 default_self 953 \family default 954 on all the complex parts that are declared locally (with 955 \family typewriter 956 IS_A 957 \family default 958 ) in the model. 959 \end_layout 960 961 \begin_layout Standard 962 This method should not run any methods on model parts that come via 963 \family typewriter 964 WILL_BE 965 \family default 966 in the definition's parameter list. 967 This method also should not change the values of variables that are passed 968 in through the parameter list. 969 Sometimes there will be nothing for this method to do. 970 Define it anyway, leaving it empty, so that any writer reusing this model 971 as part of a higher level model can safely assume it is there and call 972 it without having to know the details. 973 \end_layout 974 975 \begin_layout Standard 976 When a top-level simulation is built by the compiler, this method will be 977 run (for the top-level model) at the end of compilation. 978 If your model's 979 \family typewriter 980 default_self 981 \family default 982 method does not call the lower-level 983 \family typewriter 984 default_self 985 \family default 986 methods in your model locally-declared ( 987 \family typewriter 988 IS_A 989 \family default 990 ) parts, it is quite likely that your model will not solve. 991 \end_layout 992 993 \begin_layout Subsection 994 995 \family typewriter 996 METHOD bound_self 997 \begin_inset LatexCommand \index{bound\_self} 998 999 \end_inset 1000 1001 1002 \end_layout 1003 1004 \begin_layout Standard 1005 Much of the art of nonlinear physical modeling is in bounding the solution. 1006 This method should update the bounds on locally defined ( 1007 \family typewriter 1008 IS_A 1009 \family default 1010 ) variables and 1011 \family typewriter 1012 (IS_A) 1013 \family default 1014 defined model parts. 1015 Updating bounds requires some care. 1016 For example, the bounds on fractions frequently don't need updating. 1017 This method should not bound variables passed into the 1018 \family typewriter 1019 MODEL 1020 \family default 1021 definition or parts passed into the definition. 1022 \end_layout 1023 1024 \begin_layout Standard 1025 A common formula for updating bounds is to define a region around the current 1026 value of the variable. 1027 A linear region size formula, as an example, would be: 1028 \end_layout 1029 1030 \begin_layout Standard 1031 \begin_inset Formula 1032 x_{bound}=x\pm\Delta\cdot x_{nominal}\label{eq:methods.bound-width} 1033 1034 \end_inset 1035 1036 or, in ASCEND syntax, 1037 \end_layout 1038 1039 \begin_layout LyX-Code 1040 v.upper_bound := v + 1041 \begin_inset LatexCommand \index{boundwidth} 1042 1043 \end_inset 1044 1045 boundwidth * v.nominal; 1046 \end_layout 1047 1048 \begin_layout LyX-Code 1049 v.lower_bound := v - boundwidth * v.nominal; 1050 \end_layout 1051 1052 \begin_layout Standard 1053 Care must be taken that such a formula does not move the bounds (particularly 1054 lower bounds) out so far as to allow non-physical solutions. 1055 Logarithmic bounding regions are also simple to calculate. 1056 Here 1057 \family typewriter 1058 boundwidth 1059 \family default 1060 is a 1061 \family typewriter 1062 bound_width 1063 \family default 1064 : it could be a real atom (but 1065 \series bold 1066 not 1067 \series default 1068 a 1069 \family typewriter 1070 solver_var 1071 \family default 1072 ) or some value you can use to determine how much "wiggle-room" you want 1073 to give a solver. 1074 1075 \end_layout 1076 1077 \begin_layout Standard 1078 Small powers of 4 and 10 are usually good values of 1079 \family typewriter 1080 boundwidth 1081 \family default 1082 . 1083 Too small a boundwidth can cut off the portion of number space where the 1084 solution is found. 1085 Too large a bound width can allow solvers to wander for great distances 1086 in uninteresting regions of the number space. 1087 \end_layout 1088 1089 \begin_layout Standard 1090 \begin_inset Note Note 1091 status open 1092 1093 \begin_layout Standard 1094 We need an example here 1095 \end_layout 1096 1097 \end_inset 1098 1099 1100 \end_layout 1101 1102 \begin_layout Subsection 1103 1104 \family typewriter 1105 METHOD scale_self 1106 \begin_inset LatexCommand \index{scale\_self} 1107 1108 \end_inset 1109 1110 1111 \begin_inset LatexCommand \label{ssec:methods.scaleself} 1112 1113 \end_inset 1114 1115 1116 \end_layout 1117 1118 \begin_layout Standard 1119 Most nonlinear (and many linear) models cannot be solved without proper 1120 scaling of the variables. 1121 1122 \family typewriter 1123 scale_self 1124 \family default 1125 should reset the 1126 \family typewriter 1127 .nominal 1128 \family default 1129 value on every real variable in need of scaling. 1130 It should then call the 1131 \family typewriter 1132 scale_self 1133 \family default 1134 method on all the locally-defined ( 1135 \family typewriter 1136 IS_A 1137 \family default 1138 ) parts of the MODEL. 1139 A proper nominal is one such that you expect at the solution 1140 \end_layout 1141 1142 \begin_layout Standard 1143 \begin_inset Formula 1144 0\leq abs\left(\frac{x}{x_{nominal}}\right)\leq10\label{eq:methods.choiceNominal} 1145 1146 \end_inset 1147 1148 1149 \end_layout 1150 1151 \begin_layout Standard 1152 As one is dividing by the nominal value for the variable to establish its 1153 scaled value, zero is about the worst value you could choose for a nominal 1154 value. 1155 \end_layout 1156 1157 \begin_layout Standard 1158 This method should not change the 1159 \family typewriter 1160 .nominal 1161 \family default 1162 values for models and variables that are received through the parameter 1163 list of the model. 1164 \end_layout 1165 1166 \begin_layout Standard 1167 Variables (like fractions), when bounded such that they cannot be too far 1168 away from 1.0 in magnitude, probably don't need scaling most of the time, 1169 so long as they they are also bounded away from 0.0. 1170 1171 \end_layout 1172 1173 \begin_layout Standard 1174 Some solvers, but not all, will attempt to scale the equations and variables 1175 by heuristic matrix-based methods. 1176 This works, but inconsistently; user-defined scaling 1177 \begin_inset LatexCommand \index{scaling} 1178 1179 \end_inset 1180 1181 is generally superior. 1182 ASCEND makes scaling equations easy to do. 1183 You scale the variables, which can only be done well by knowing something 1184 about where the solution is going to be found (by being an engineer, for 1185 example). 1186 Then ASCEND can calculate an appropriate equation-scaling by efficient 1187 symbolic methods. 1188 \end_layout 1189 1190 \begin_layout Section 1191 The 1192 \family typewriter 1193 *_all 1194 \family default 1195 methods 1196 \begin_inset LatexCommand \label{sec:methods.allMethods} 1197 1198 \end_inset 1199 1200 1201 \end_layout 1202 1203 \begin_layout Subsection 1204 1205 \family typewriter 1206 METHOD default_all 1207 \begin_inset LatexCommand \index{default\_all} 1208 1209 \end_inset 1210 1211 1212 \end_layout 1213 1214 \begin_layout Standard 1215 Above we discussed the ability in ASCEND to isolate and solve any part of 1216 a model that is defined as an instance of a single type requires you initialize 1217 the arguments to a model that you are isolating. 1218 This method should run the 1219 \family typewriter 1220 default_all 1221 \family default 1222 method on each of the parts received through the parameter list via 1223 \family typewriter 1224 WILL_BE 1225 \family default 1226 statements and should give appropriate default values to any variables 1227 received through the parameter list. 1228 After these calls and settings have been done, it should then call its 1229 own 1230 \family typewriter 1231 default_self 1232 \family default 1233 to take care of all local defaults. 1234 \end_layout 1235 1236 \begin_layout Subsection 1237 1238 \family typewriter 1239 METHOD check_all 1240 \begin_inset LatexCommand \index{check\_all} 1241 1242 \end_inset 1243 1244 1245 \end_layout 1246 1247 \begin_layout Standard 1248 When solving only a part of a simulation, it is necessary to check the models 1249 and variables passed into the part as well as the locally defined parts 1250 and variables. 1251 This method should call 1252 \family typewriter 1253 check_all 1254 \family default 1255 on the parts received as 1256 \family typewriter 1257 WILL_BE 1258 \family default 1259 parameters, then call 1260 \family typewriter 1261 check_self 1262 \family default 1263 to check the locally defined parts and equations. 1264 \end_layout 1265 1266 \begin_layout Subsection 1267 1268 \family typewriter 1269 METHOD bound_all 1270 \begin_inset LatexCommand \index{bound\_all} 1271 1272 \end_inset 1273 1274 1275 \end_layout 1276 1277 \begin_layout Standard 1278 This method should be like 1279 \family typewriter 1280 bound_self 1281 \family default 1282 except that it bounds the passed in variables and calls 1283 \family typewriter 1284 bound_all 1285 \family default 1286 on the passed in parts. 1287 It should then call 1288 \family typewriter 1289 bound_self 1290 \family default 1291 . 1292 \end_layout 1293 1294 \begin_layout Subsection 1295 1296 \family typewriter 1297 METHOD scale_all 1298 \begin_inset LatexCommand \index{scale\_all} 1299 1300 \end_inset 1301 1302 1303 \end_layout 1304 1305 \begin_layout Standard 1306 This method should be like 1307 \family typewriter 1308 scale_self 1309 \family default 1310 above except that it scales the variables received through the parameter 1311 list and calls 1312 \family typewriter 1313 scale_all 1314 \family default 1315 on the passed in parts. 1316 It should then call 1317 \family typewriter 1318 scale_self 1319 \family default 1320 to take care of the local variables and models. 1321 \end_layout 1322 1323 \begin_layout Section 1324 1325 \family typewriter 1326 METHOD specify 1327 \family default 1328 1329 \begin_inset LatexCommand \index{specify} 1330 1331 \end_inset 1332 1333 1334 \end_layout 1335 1336 \begin_layout Standard 1337 The method 1338 \family typewriter 1339 specify 1340 \family default 1341 sets the 1342 \family typewriter 1343 .fixed 1344 \family default 1345 flags so an instance of the model is solvable. 1346 There are two issues involved. 1347 First, the model must be square - i.e., it must have as many free variables 1348 as it has eligible equations available to compute them. 1349 Second, it should be a setting of 1350 \family typewriter 1351 .fixed 1352 \family default 1353 flags that the modeler knows will solve numerically. 1354 This latter requirement requires one to have an intuitive feel for the 1355 model. 1356 A chemical engineer will 1357 \begin_inset Quotes eld 1358 \end_inset 1359 1360 know 1361 \begin_inset Quotes erd 1362 \end_inset 1363 1364 that a flash calculation, where he has fixed both the pressure and the 1365 vapor fraction, is a pretty robust calculation. 1366 It would be a good way to set fix flags in the 1367 \family typewriter 1368 specify 1369 \family default 1370 method. 1371 Getting the 1372 \family typewriter 1373 .fixed 1374 \family default 1375 flags set for a large complex model is one of the hardest tasks ever invented 1376 by mathematicians if you go about it in the wrong way. 1377 If you follow the prescription here, getting the right number of flags 1378 set is almost automatic. 1379 We have set written the specify methods for a complex hierarchy of models 1380 correctly the first time using this approach. 1381 \end_layout 1382 1383 \begin_layout Standard 1384 We shall illustrate this section by examining the set of models in 1385 \family typewriter 1386 simple_fs.a4c 1387 \family default 1388 . 1389 You should find that model in the model directory for ASCEND and open it 1390 in your favorite text editor. 1391 This model is for a simple flowsheet comprising a mixer, a reactor, a flash 1392 unit and a simple stream splitter. 1393 It contains the following models: 1394 \family typewriter 1395 mixture 1396 \family default 1397 , 1398 \family typewriter 1399 molar_stream 1400 \family default 1401 , 1402 \family typewriter 1403 mixer 1404 \family default 1405 , 1406 \family typewriter 1407 reactor 1408 \family default 1409 , 1410 \family typewriter 1411 flash 1412 \family default 1413 , 1414 \family typewriter 1415 splitter 1416 \family default 1417 , 1418 \family typewriter 1419 flowsheet 1420 \family default 1421 , 1422 \family typewriter 1423 controller 1424 \family default 1425 , 1426 \family typewriter 1427 test_flowsheet 1428 \family default 1429 and 1430 \family typewriter 1431 test_controller 1432 \family default 1433 . 1434 When compiling and solving, one typically creates an instance of 1435 \family typewriter 1436 test_controller 1437 \family default 1438 . 1439 1440 \end_layout 1441 1442 \begin_layout Standard 1443 Model mixture only defines new variables 1444 \family typewriter 1445 y[components] 1446 \family default 1447 and one equation that says their sum is unity. 1448 Model molar_stream introduces new variables 1449 \family typewriter 1450 Ftot 1451 \family default 1452 and 1453 \family typewriter 1454 f[components] 1455 \family default 1456 . 1457 It also introduces an instance of the model mixture, which it calls 1458 \family typewriter 1459 state 1460 \family default 1461 . 1462 Finally it introduces locally the equations 1463 \family typewriter 1464 f_def 1465 \family default 1466 , one for each component. 1467 Models 1468 \family typewriter 1469 mixer 1470 \family default 1471 , 1472 \family typewriter 1473 reactor 1474 \family default 1475 , 1476 \family typewriter 1477 flash 1478 \family default 1479 and 1480 \family typewriter 1481 splitter 1482 \family default 1483 introduce their own local variables and equations. 1484 Each also defines it input and output streams as instances of the model 1485 1486 \family typewriter 1487 molar_stream 1488 \family default 1489 . 1490 Model 1491 \family typewriter 1492 flowsheet 1493 \family default 1494 contains a 1495 \family typewriter 1496 mixer 1497 \family default 1498 , 1499 \family typewriter 1500 reactor 1501 \family default 1502 , 1503 \family typewriter 1504 flash 1505 \family default 1506 and 1507 \family typewriter 1508 splitter 1509 \family default 1510 , etc. 1511 \end_layout 1512 1513 \begin_layout Standard 1514 Assume you have just written a set of models, such as those in 1515 \family typewriter 1516 simple_fs.a4c 1517 \family default 1518 . 1519 In this approach you should start with the lowest level models - i.e., the 1520 ones that only introduce (using 1521 \family typewriter 1522 IS_A 1523 \family default 1524 statements) new variables and new parts that are instances of types in 1525 existing ASCEND libraries. 1526 The lowest level model by this definition is 1527 \family typewriter 1528 mixture 1529 \family default 1530 . 1531 It only introduces new variables and one new equation. 1532 Once you have written and debugged a 1533 \family typewriter 1534 specify 1535 \family default 1536 method for 1537 \family typewriter 1538 mixture 1539 \family default 1540 , then again look for any model that only introduces new variables and local 1541 equations and/or parts for which a debugged 1542 \family typewriter 1543 specify 1544 \family default 1545 method exists. 1546 The model 1547 \family typewriter 1548 molar_stream 1549 \family default 1550 is such a model and can be considered next. 1551 It introduces a part which is an instance of 1552 \family typewriter 1553 mixture 1554 \family default 1555 for which we already have a 1556 \family typewriter 1557 specify 1558 \family default 1559 method. 1560 Once we have a debugged 1561 \family typewriter 1562 specify 1563 \family default 1564 method for 1565 \family typewriter 1566 molar_stream 1567 \family default 1568 , then we can consider any of the models 1569 \family typewriter 1570 mixer 1571 \family default 1572 , 1573 \family typewriter 1574 reactor 1575 \family default 1576 , 1577 \family typewriter 1578 flash 1579 \family default 1580 and 1581 \family typewriter 1582 splitter 1583 \family default 1584 - they only have parts that are instances of 1585 \family typewriter 1586 molar_stream 1587 \family default 1588 . 1589 After creating and debugging their 1590 \family typewriter 1591 specify 1592 \family default 1593 methods, we can consider the model 1594 \family typewriter 1595 flowsheet 1596 \family default 1597 , then 1598 \family typewriter 1599 controller 1600 \family default 1601 , then 1602 \family typewriter 1603 test_flowsheet 1604 \family default 1605 and finally 1606 \family typewriter 1607 test_controller 1608 \family default 1609 . 1610 \end_layout 1611 1612 \begin_layout Standard 1613 The safest way to set 1614 \family typewriter 1615 .fixed 1616 \family default 1617 flags is first to clear all the 1618 \family typewriter 1619 .fixed 1620 \family default 1621 flags for a model instance by running the method 1622 \family typewriter 1623 ClearAll 1624 \family default 1625 . 1626 The method 1627 \family typewriter 1628 specify 1629 \family default 1630 does 1631 \series bold 1632 not 1633 \series default 1634 run 1635 \family typewriter 1636 ClearAll 1637 \family default 1638 , but we always write our 1639 \family typewriter 1640 specify 1641 \family default 1642 methods assuming 1643 \family typewriter 1644 ClearAll 1645 \family default 1646 has just been run and thus that all 1647 \family typewriter 1648 .fixed 1649 \family default 1650 flags are set to false. 1651 The following steps will aid you to write, almost automatically, a 1652 \family typewriter 1653 specify 1654 \family default 1655 method that fixes the correct number of 1656 \family typewriter 1657 .fixed 1658 \family default 1659 flags. 1660 \end_layout 1661 1662 \begin_layout Enumerate 1663 Find all locally defined solver variables (of type 1664 \family typewriter 1665 solver_var 1666 \family default 1667 - e.g., 1668 \family typewriter 1669 y[components] 1670 \family default 1671 are of type 1672 \family typewriter 1673 fraction 1674 \family default 1675 which is of type 1676 \family typewriter 1677 solver_var 1678 \family default 1679 ). 1680 In mixture, the statement 1681 \begin_inset Quotes eld 1682 \end_inset 1683 1684 1685 \family typewriter 1686 y[components] IS_A fraction; 1687 \family default 1688 1689 \begin_inset Quotes erd 1690 \end_inset 1691 1692 introduces new 1693 \family typewriter 1694 solver_var 1695 \family default 1696 s, one for each element in the set 1697 \family typewriter 1698 components 1699 \family default 1700 . 1701 Let us assume there are 1702 \family typewriter 1703 nc 1704 \family default 1705 such elements. 1706 \end_layout 1707 1708 \begin_layout Enumerate 1709 Find locally introduced equations. 1710 In 1711 \family typewriter 1712 mixture 1713 \family default 1714 , there is one such equation that says the variables 1715 \family typewriter 1716 y 1717 \family default 1718 add up to one. 1719 \end_layout 1720 1721 \begin_layout Enumerate 1722 Find all new parts that are instances of previously defined types. 1723 In 1724 \family typewriter 1725 mixture 1726 \family default 1727 , there are no new parts. 1728 \end_layout 1729 1730 \begin_layout Enumerate 1731 You must set 1732 \family typewriter 1733 .fixed 1734 \family default 1735 flags locally equal in number to the number of new locally defined 1736 \family typewriter 1737 solver_var 1738 \family default 1739 s minus the number of new locally defined equations. 1740 In 1741 \family typewriter 1742 mixture 1743 \family default 1744 you must write set one 1745 \family typewriter 1746 fixed 1747 \family default 1748 flag to true for all but one of the components as there are 1749 \family typewriter 1750 nc 1751 \family default 1752 new locally introduced variables and one new locally introduced equation. 1753 The 1754 \family typewriter 1755 CHOICE 1756 \family default 1757 function arbitrarily selects one element of the set (in set theory, you 1758 cannot identify a set element as being first, another as second, etc, so 1759 for purity's sake, we only give you the option of letting ASCEND pick one 1760 arbitrarily). 1761 Thus we set all 1762 \family typewriter 1763 nc 1764 \family default 1765 flags and then clear one. 1766 \end_layout 1767 1768 \begin_layout Enumerate 1769 You must run the 1770 \family typewriter 1771 specify 1772 \family default 1773 method for each new part. 1774 Here there are none. 1775 Running specify will guarantee each part is 1776 \begin_inset Quotes eld 1777 \end_inset 1778 1779 square 1780 \begin_inset Quotes erd 1781 \end_inset 1782 1783 - i.e., after being run, the part will not alter the number of degrees of 1784 freedom for the current model definition. 1785 However, the same 1786 \family typewriter 1787 solver_var 1788 \family default 1789 may get fixed in two or more different parts if those parts share that 1790 1791 \family typewriter 1792 solver_var 1793 \family default 1794 , and you will have to discover this sharing and add special statements 1795 to correct this type of multiple setting of the same flag. 1796 This discovery will best be done by compiling an instance of the type and 1797 using the Find By Type tool in the Browser. 1798 Its default setting is to find all 1799 \family typewriter 1800 solver_vars 1801 \family default 1802 with 1803 \family typewriter 1804 .fixed 1805 \family default 1806 equal to 1807 \family typewriter 1808 TRUE 1809 \family default 1810 , exactly what you need to aid you with this task. 1811 You may also wish to change in minor ways the flag setting that the parts 1812 do to suit the needs of the current type definition - you may wish to free 1813 1814 \family typewriter 1815 temperature 1816 \family default 1817 and fix 1818 \family typewriter 1819 pressure 1820 \family default 1821 for a stream, for example, when the stream is part of a higher level model. 1822 \end_layout 1823 1824 \begin_layout Standard 1825 Look now at the 1826 \family typewriter 1827 molar_stream 1828 \family default 1829 model. 1830 Running 1831 \family typewriter 1832 ClearAll 1833 \family default 1834 for an instance of 1835 \family typewriter 1836 molar_stream 1837 \family default 1838 will clear all the 1839 \family typewriter 1840 .fixed 1841 \family default 1842 flags for it and all its parts. 1843 It introduces 1844 \family typewriter 1845 Ftot 1846 \family default 1847 and 1848 \family typewriter 1849 f[components] 1850 \family default 1851 as local new solver variables. 1852 It also introduces one new equation for each component, one less than the 1853 number of new variables. 1854 Finally it introduces a new part called 1855 \family typewriter 1856 state 1857 \family default 1858 . 1859 We have partitioned the 1860 \family typewriter 1861 specify 1862 \family default 1863 method into two methods here for 1864 \begin_inset Quotes eld 1865 \end_inset 1866 1867 chemical engineering reasons, 1868 \begin_inset Quotes erd 1869 \end_inset 1870 1871 one of which runs the other. 1872 Think of what the two of them accomplish as the 1873 \family typewriter 1874 specify 1875 \family default 1876 method we wish to create. 1877 First we run the 1878 \family typewriter 1879 specify 1880 \family default 1881 method for the new part: 1882 \family typewriter 1883 state 1884 \family default 1885 . 1886 That will set the 1887 \family typewriter 1888 .fixed 1889 \family default 1890 flags for 1891 \family typewriter 1892 nc-1 1893 \family default 1894 of the variables 1895 \family typewriter 1896 state.y[components] 1897 \family default 1898 . 1899 Then, as there is one more variable than equation in this model, we must 1900 set a net of one added 1901 \family typewriter 1902 .fixed 1903 \family default 1904 flag. 1905 We accomplish this by first clearing all the flags for the variables 1906 \family typewriter 1907 state.y[components] 1908 \family default 1909 -- one of which was already clear -- and then fixing all the variables 1910 1911 \family typewriter 1912 f[components] 1913 \family default 1914 . 1915 We cleared 1916 \family typewriter 1917 nc-1 1918 \family default 1919 flags and set 1920 \family typewriter 1921 nc 1922 \family default 1923 for a net of one new flag being set. 1924 For our 1925 \family typewriter 1926 molar_stream 1927 \family default 1928 model, we would prefer that the variables 1929 \family typewriter 1930 f[components] 1931 \family default 1932 are the ones we fix. 1933 \end_layout 1934 1935 \begin_layout Standard 1936 Lastly, look at the 1937 \family typewriter 1938 reactor 1939 \family default 1940 model. 1941 We introduce 1942 \family typewriter 1943 nc+1 1944 \family default 1945 new variables: 1946 \family typewriter 1947 stoich_coef[feed.components] 1948 \family default 1949 and 1950 \family typewriter 1951 turnover 1952 \family default 1953 . 1954 We also introduce 1955 \family typewriter 1956 nc 1957 \family default 1958 new equations. 1959 Lastly we introduce two parts 1960 \family typewriter 1961 feed 1962 \family default 1963 and 1964 \family typewriter 1965 out 1966 \family default 1967 , which are 1968 \family typewriter 1969 molar_stream 1970 \family default 1971 s. 1972 The 1973 \family typewriter 1974 specify 1975 \family default 1976 method, again a combination of 1977 \family typewriter 1978 specify 1979 \family default 1980 and 1981 \family typewriter 1982 seqmod 1983 \family default 1984 , must set a net of one new 1985 \family typewriter 1986 .fixed 1987 \family default 1988 flag. 1989 The way it does it is 1990 \begin_inset Quotes eld 1991 \end_inset 1992 1993 tricky 1994 \begin_inset Quotes erd 1995 \end_inset 1996 1997 but not difficult to follow. 1998 In 1999 \family typewriter 2000 seqmod 2001 \family default 2002 , we fix 2003 \family typewriter 2004 turnover 2005 \family default 2006 and all 2007 \family typewriter 2008 nc 2009 \family default 2010 of the variables 2011 \family typewriter 2012 stoich_coef 2013 \family default 2014 . 2015 We seem to have fixed 2016 \family typewriter 2017 nc 2018 \family default 2019 too many. 2020 In 2021 \family typewriter 2022 specify 2023 \family default 2024 , which first runs 2025 \family typewriter 2026 seqmod 2027 \family default 2028 , we only run the 2029 \family typewriter 2030 specify 2031 \family default 2032 method for 2033 \family typewriter 2034 feed 2035 \family default 2036 and 2037 \series bold 2038 not 2039 \series default 2040 the 2041 \family typewriter 2042 specify 2043 \family default 2044 method for 2045 \family typewriter 2046 out 2047 \family default 2048 . 2049 We know that not running the 2050 \family typewriter 2051 specify 2052 \family default 2053 method for 2054 \family typewriter 2055 out 2056 \family default 2057 , a 2058 \family typewriter 2059 molar_stream 2060 \family default 2061 as we just discussed above, will leave us with 2062 \family typewriter 2063 nc 2064 \family default 2065 2066 \family typewriter 2067 .fixed 2068 \family default 2069 flags not set. 2070 So we deviously traded these flags for those belonging to 2071 \family typewriter 2072 stoich_coef 2073 \family default 2074 , giving us a net of fixing one flag. 2075 If we had abided by all the steps above, we would have run the 2076 \family typewriter 2077 specify 2078 \family default 2079 method for 2080 \family typewriter 2081 out 2082 \family default 2083 , then gone in and cleared the flags for 2084 \family typewriter 2085 out.f[components] 2086 \family default 2087 while setting those for 2088 \family typewriter 2089 stoich_coef[components] 2090 \family default 2091 in trade to get the flags we want set for this model. 2092 We did the equivalent with a shortcut. 2093 \end_layout 2094 2095 \begin_layout Standard 2096 If a model is parametric, the models defined by 2097 \family typewriter 2098 WILL_BE 2099 \family default 2100 in the parameter list should be viewed as new variables defined in the 2101 model. 2102 Remember 2103 \family typewriter 2104 specify 2105 \family default 2106 must fix sufficient variables to make an instance of this model square. 2107 \end_layout 2108 2109 \begin_layout Standard 2110 At each of the above steps, pay special attention to indexed variables used 2111 in 2112 \emph on 2113 indexed 2114 \emph default 2115 equations 2116 \begin_inset Note Note 2117 status collapsed 2118 2119 \begin_layout Standard 2120 need a cross reference here to the appropriate part of the manual 2121 \end_layout 2122 2123 \end_inset 2124 2125 . 2126 Frequently you must fix or free 2127 \family typewriter 2128 n 2129 \family default 2130 or 2131 \family typewriter 2132 n-1 2133 \family default 2134 variables indexed over a set of size 2135 \family typewriter 2136 n 2137 \family default 2138 , if there are 2139 \family typewriter 2140 n 2141 \family default 2142 matching equations. 2143 In general, if you think you have 2144 \family typewriter 2145 specify 2146 \family default 2147 correctly written, change the sizes of all the sets in your MODEL by one 2148 and then by two members. 2149 If your 2150 \family typewriter 2151 specify 2152 \family default 2153 method still works, you are probably using sets correctly. 2154 Pursuing 'symmetry', i.e. 2155 the identical treatment of all variables defined in a single array, usually 2156 helps you write 2157 \family typewriter 2158 specify 2159 \family default 2160 correctly. 2161 \end_layout 2162 2163 \begin_layout Standard 2164 When writing models that combine parts which do not share very well, or 2165 which both try to compute the same variable in different ways, it may even 2166 be necessary to write a 2167 \family typewriter 2168 WHEN 2169 \family default 2170 statement to selectively 'turn off' the conflicting equations or model 2171 fragments. 2172 An object or equation 2173 \family typewriter 2174 USE 2175 \family default 2176 d in any 2177 \family typewriter 2178 WHEN 2179 \family default 2180 statement is turned off by default and becomes a part of the solved 2181 \family typewriter 2182 MODEL 2183 \family default 2184 only when the condition of some 2185 \family typewriter 2186 CASE 2187 \family default 2188 that 2189 \family typewriter 2190 USE 2191 \family default 2192 s that object is matched. 2193 \end_layout 2194 2195 \begin_layout Standard 2196 The setting of boolean, integer, and symbol variables that are controlling 2197 conditions of 2198 \family typewriter 2199 WHEN 2200 \family default 2201 and 2202 \family typewriter 2203 SWITCH 2204 \family default 2205 statements should be done in the 2206 \family typewriter 2207 specify 2208 \family default 2209 method. 2210 \end_layout 2211 2212 \begin_layout Standard 2213 There is no 'one perfect' 2214 \family typewriter 2215 specify 2216 \family default 2217 method for all purposes. 2218 This routine should merely define a reasonably useful base configuration 2219 of the model. 2220 Other 2221 \family typewriter 2222 specify_whatElseYouWant 2223 \family default 2224 methods can also be written. 2225 \end_layout 2226 2227 \begin_layout Section 2228 2229 \family typewriter 2230 METHOD values 2231 \begin_inset LatexCommand \index{values} 2232 2233 \end_inset 2234 2235 2236 \end_layout 2237 2238 \begin_layout Standard 2239 In a final application 2240 \family typewriter 2241 MODEL 2242 \family default 2243 , you should record at least one set of input values (values of the fixed 2244 variables and guesses of key solved-for variables) that leads to a good 2245 solution. 2246 This facilitates testing of the model, and helps the next person using 2247 your model to be assured that it works as expected. 2248 \end_layout 2249 2250 \begin_layout Section 2251 Summary 2252 \end_layout 2253 2254 \begin_layout Standard 2255 \begin_inset Marginal 2256 status collapsed 2257 2258 \begin_layout Standard 2259 adding our standard methods to a model definition 2260 \end_layout 2261 2262 \end_inset 2263 2264 We have defined a set of standard methods for ASCEND models which we insist 2265 a modeler provide before we will allow a model to be placed in any of our 2266 model libraries. 2267 These are listed in Table 2268 \begin_inset LatexCommand \ref{tab:methods.stdMethodReqd} 2269 2270 \end_inset 2271 2272 2273 \noun off 2274 . 2275 As should be evident from above, not all models must have associated methods; 2276 our first vessel model did not. 2277 It is simply our policy that models in our libraries must have these methods 2278 to promote model reuse and to serve as examples of best practices in mathematic 2279 al modeling. 2280 \end_layout 2281 2282 \begin_layout Standard 2283 \begin_inset Float table 2284 wide false 2285 sideways false 2286 status open 2287 2288 \begin_layout Caption 2289 \begin_inset LatexCommand \label{tab:methods.stdMethodReqd} 2290 2291 \end_inset 2292 2293 Standard methods required for types in our ASCEND model library 2294 \end_layout 2295 2296 \begin_layout Standard 2297 \begin_inset Tabular 2298 2299 2300 2301 2302 2303 2304 \begin_inset Text 2305 2306 \begin_layout Standard 2307 method 2308 \end_layout 2309 2310 \end_inset 2311 2312 2313 \begin_inset Text 2314 2315 \begin_layout Standard 2316 description 2317 \end_layout 2318 2319 \end_inset 2320 2321 2322 2323 2324 \begin_inset Text 2325 2326 \begin_layout Standard 2327 2328 \family typewriter 2329 default_self 2330 \end_layout 2331 2332 \end_inset 2333 2334 2335 \begin_inset Text 2336 2337 \begin_layout Standard 2338 a method called automatically when any simulation is compiled to provide 2339 default values and adjust bounds for any locally created variables which 2340 may have unsuitable defaultsin their ATOM definitions. 2341 Usually the variables selected are those for which the model becomes ill-behave 2342 d if given poor initial guesses or bounds (e.g., zero). 2343 This method should include statements to run the default_self method for 2344 each of its locally created (IS_A'd) parts. 2345 This method should be written first. 2346 \end_layout 2347 2348 \end_inset 2349 2350 2351 2352 2353 \begin_inset Text 2354 2355 \begin_layout Standard 2356 2357 \family typewriter 2358 ClearAll 2359 \end_layout 2360 2361 \end_inset 2362 2363 2364 \begin_inset Text 2365 2366 \begin_layout Standard 2367 a method to set all the fixed flags for variables in the type to FALSE. 2368 This puts these flags into a known standard state -- i.e., all are FALSE. 2369 All models inherit this method from the base model and the need to rewrite 2370 it is very, very rare. 2371 2372 \end_layout 2373 2374 \end_inset 2375 2376 2377 2378 2379 \begin_inset Text 2380 2381 \begin_layout Standard 2382 2383 \family typewriter 2384 specify 2385 \end_layout 2386 2387 \end_inset 2388 2389 2390 \begin_inset Text 2391 2392 \begin_layout Standard 2393 a method which assumes all the 2394 \family typewriter 2395 fixed 2396 \family default 2397 flags are currently 2398 \family typewriter 2399 FALSE 2400 \family default 2401 and which then sets a suitable set of fixed flags to 2402 \family typewriter 2403 TRUE 2404 \family default 2405 to make an instance of this type of model well-posed. 2406 A well-posed model is one that is square ( 2407 \begin_inset Formula $n$ 2408 \end_inset 2409 2410 equations in 2411 \begin_inset Formula $n$ 2412 \end_inset 2413 2414 unknowns) and solvable. 2415 2416 \end_layout 2417 2418 \end_inset 2419 2420 2421 2422 2423 \begin_inset Text 2424 2425 \begin_layout Standard 2426 2427 \family typewriter 2428 reset 2429 \end_layout 2430 2431 \end_inset 2432 2433 2434 \begin_inset Text 2435 2436 \begin_layout Standard 2437 a method which first runs the 2438 \family typewriter 2439 ClearAll 2440 \family default 2441 method and then the 2442 \family typewriter 2443 specify 2444 \family default 2445 method. 2446 We include this method because it is very convenient. 2447 We only have to run one method to make any simulation well-posed, no matter 2448 how its fixed flags are currently set. 2449 All models inherit this method from the base model, as with 2450 \family typewriter 2451 ClearAll 2452 \family default 2453 . 2454 2455 \end_layout 2456 2457 \end_inset 2458 2459 2460 2461 2462 \begin_inset Text 2463 2464 \begin_layout Standard 2465 2466 \family typewriter 2467 values 2468 \end_layout 2469 2470 \end_inset 2471 2472 2473 \begin_inset Text 2474 2475 \begin_layout Standard 2476 a method to establish typical values for the variables we have fixed in 2477 an application or test model. 2478 We may also supply values for some of the variables we will be computing 2479 to aid in solving a model instance of this type. 2480 These values are ones that we have tested for simulation of this type and 2481 found good. 2482 2483 \end_layout 2484 2485 \end_inset 2486 2487 2488 2489 2490 \begin_inset Text 2491 2492 \begin_layout Standard 2493 2494 \family typewriter 2495 bound_self 2496 \end_layout 2497 2498 \end_inset 2499 2500 2501 \begin_inset Text 2502 2503 \begin_layout Standard 2504 a method to update the 2505 \family typewriter 2506 .upper_bound 2507 \family default 2508 and 2509 \family typewriter 2510 .lower_bound 2511 \family default 2512 value for each of the variables. 2513 ASCEND solvers use these bound values to help solve the model equations. 2514 This method should bound locally created variables and then call 2515 \family typewriter 2516 bound_self 2517 \family default 2518 for every locally created ( 2519 \family typewriter 2520 IS_A 2521 \family default 2522 'd) part. 2523 2524 \end_layout 2525 2526 \end_inset 2527 2528 2529 2530 2531 \begin_inset Text 2532 2533 \begin_layout Standard 2534 2535 \family typewriter 2536 scale_self 2537 \end_layout 2538 2539 \end_inset 2540 2541 2542 \begin_inset Text 2543 2544 \begin_layout Standard 2545 a method to update the 2546 \family typewriter 2547 .nominal 2548 \family default 2549 value for each of the variables. 2550 ASCEND solvers will use these nominal values to rescale the variable to 2551 have a value of about one in magnitude to help solve the model equations. 2552 This method should re-scale locally created variables and then call 2553 \family typewriter 2554 scale_self 2555 \family default 2556 for every locally created ( 2557 \family typewriter 2558 IS_A 2559 \family default 2560 'd) part. 2561 2562 \end_layout 2563 2564 \end_inset 2565 2566 2567 2568 2569 \end_inset 2570 2571 2572 \end_layout 2573 2574 \end_inset 2575 2576 2577 \end_layout 2578 2579 \begin_layout Section 2580 Method writing automation 2581 \begin_inset LatexCommand \label{sec:methods.automation} 2582 2583 \end_inset 2584 2585 2586 \end_layout 2587 2588 \begin_layout Standard 2589 \begin_inset Marginal 2590 status collapsed 2591 2592 \begin_layout Standard 2593 Hit the button Library/Edit/Suggest methods and tweak the results 2594 \end_layout 2595 2596 \end_inset 2597 2598 ASCEND will help you write the standard methods. 2599 Writing most of the standard methods can be nearly automated once the declarati 2600 ve portion of the model definition is written. 2601 Usually, however, some minor tweaking of the automatically generated code 2602 is needed. 2603 In the Library window, the Edit menu has a "Suggest methods" button. 2604 Select a model you have written and read into the library, then hit this 2605 button. 2606 2607 \end_layout 2608 2609 \begin_layout Standard 2610 In the Display window will appear a good starting point for the standard 2611 methods that you have not yet defined. 2612 This starting point follows the guidelines in this chapter. 2613 It saves you a lot of typing but it is a starting point only. 2614 Select and copy the text into the model you are editing, then tailor it 2615 to your needs and finish the missing bits. 2616 The comments in the generated code can be deleted before or after you copy 2617 the text to your model file. 2618 \end_layout 2619 2620 \begin_layout Standard 2621 If you have suggestions for general improvements to the generated method 2622 code, please mail them to us and include a sample of what the generated 2623 code ought to look like before the user performs any hand-editing. 2624 We aim to create easily understood and easily fixed method suggestions, 2625 not perfect suggestions, because procedural code style tastes vary so widely. 2626 \end_layout 2627 2628 \begin_layout Standard 2629 \begin_inset Note Note 2630 status open 2631 2632 \begin_layout Standard 2633 Closing the chapter you find below the suggested methods ASCEND generates 2634 for the ***vessel*** model. 2635 \end_layout 2636 2637 \end_inset 2638 2639 2640 \end_layout 2641 2642 \end_body 2643 \end_document