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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 825 - (show annotations) (download) (as text)
Mon Aug 21 23:41:31 2006 UTC (16 years, 1 month ago) by johnpye
Original Path: trunk/doc/lyxFinal/howto-methods.lyx
File MIME type: application/x-lyx
File size: 56027 byte(s)
Copying documentation into code tree
1 #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 \begin{equation}
1032 x_{bound}=x\pm\Delta\cdot x_{nominal}\label{eq:methods.bound-width}\end{equation}
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 \begin{equation}
1144 0\leq abs\left(\frac{x}{x_{nominal}}\right)\leq10\label{eq:methods.choiceNominal}\end{equation}
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 <lyxtabular version="3" rows="8" columns="2">
2299 <features islongtable="true">
2300 <column alignment="center" valignment="top" leftline="true" width="0">
2301 <column alignment="center" valignment="top" leftline="true" rightline="true" width="4in">
2302 <row topline="true" bottomline="true">
2303 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2304 \begin_inset Text
2305
2306 \begin_layout Standard
2307 method
2308 \end_layout
2309
2310 \end_inset
2311 </cell>
2312 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2313 \begin_inset Text
2314
2315 \begin_layout Standard
2316 description
2317 \end_layout
2318
2319 \end_inset
2320 </cell>
2321 </row>
2322 <row topline="true">
2323 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2324 \begin_inset Text
2325
2326 \begin_layout Standard
2327
2328 \family typewriter
2329 default_self
2330 \end_layout
2331
2332 \end_inset
2333 </cell>
2334 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
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 </cell>
2350 </row>
2351 <row topline="true">
2352 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2353 \begin_inset Text
2354
2355 \begin_layout Standard
2356
2357 \family typewriter
2358 ClearAll
2359 \end_layout
2360
2361 \end_inset
2362 </cell>
2363 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
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 </cell>
2376 </row>
2377 <row topline="true">
2378 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2379 \begin_inset Text
2380
2381 \begin_layout Standard
2382
2383 \family typewriter
2384 specify
2385 \end_layout
2386
2387 \end_inset
2388 </cell>
2389 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
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 </cell>
2420 </row>
2421 <row topline="true">
2422 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2423 \begin_inset Text
2424
2425 \begin_layout Standard
2426
2427 \family typewriter
2428 reset
2429 \end_layout
2430
2431 \end_inset
2432 </cell>
2433 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
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 </cell>
2459 </row>
2460 <row topline="true">
2461 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2462 \begin_inset Text
2463
2464 \begin_layout Standard
2465
2466 \family typewriter
2467 values
2468 \end_layout
2469
2470 \end_inset
2471 </cell>
2472 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
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 </cell>
2487 </row>
2488 <row topline="true">
2489 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2490 \begin_inset Text
2491
2492 \begin_layout Standard
2493
2494 \family typewriter
2495 bound_self
2496 \end_layout
2497
2498 \end_inset
2499 </cell>
2500 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
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 </cell>
2528 </row>
2529 <row topline="true" bottomline="true">
2530 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2531 \begin_inset Text
2532
2533 \begin_layout Standard
2534
2535 \family typewriter
2536 scale_self
2537 \end_layout
2538
2539 \end_inset
2540 </cell>
2541 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
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 </cell>
2566 </row>
2567 </lyxtabular>
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

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