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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

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