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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 825 - (hide 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 johnpye 825 #LyX 1.4.1 created this file. For more info see http://www.lyx.org/
2     \lyxformat 245
3     \begin_document
4     \begin_header
5     \textclass book
6     \language english
7     \inputencoding auto
8     \fontscheme default
9     \graphics default
10     \paperfontsize default
11     \spacing single
12     \papersize a4paper
13     \use_geometry false
14     \use_amsmath 2
15     \cite_engine basic
16     \use_bibtopic false
17     \paperorientation portrait
18     \secnumdepth 3
19     \tocdepth 3
20     \paragraph_separation indent
21     \defskip medskip
22     \quotes_language english
23     \papercolumns 1
24     \papersides 2
25     \paperpagestyle default
26     \tracking_changes false
27     \output_changes true
28     \end_header
29    
30     \begin_body
31    
32     \begin_layout Chapter
33     Writing METHODs
34     \begin_inset LatexCommand \label{cha:methods}
35    
36     \end_inset
37    
38    
39     \end_layout
40    
41     \begin_layout Standard
42     In this chapter we describe a methodology (pun intended) which can help
43     make anyone who can solve a quadratic equation a mathematical modeling
44     expert.
45     This methodology helps you to avoid mistakes and to find mistakes quickly
46     when you make them.
47     Finding bugs weeks after creating a model is annoying, inefficient, and
48     (frequently) embarrassing.
49     Because METHOD code can be large, we do not include many examples here.
50    
51     \begin_inset Note Note
52     status collapsed
53    
54     \begin_layout Standard
55     See ***vessel something*** for detailed examples
56     \end_layout
57    
58     \end_inset
59    
60     One of the advantages of this methodology is that it allows almost automatic
61     \begin_inset LatexCommand \index{methods, automatic generation}
62    
63     \end_inset
64    
65     generation of methods for a model based on the declarative structure (defined
66     parts and variables) in the model, as we shall see in Section\InsetSpace ~
67    
68     \begin_inset LatexCommand \ref{sec:methods.automation}
69    
70     \end_inset
71    
72    
73     \noun off
74     .
75     Even if you skip much of this chapter, read
76     \noun default
77     Section\InsetSpace ~
78    
79     \noun off
80    
81     \begin_inset LatexCommand \ref{sec:methods.automation}
82    
83     \end_inset
84    
85    
86     \end_layout
87    
88     \begin_layout Standard
89     We divide methods into
90     \family typewriter
91     _self
92     \family default
93     and
94     \family typewriter
95     _all
96     \family default
97     categories.
98     The premise of our approach to design methods is that we can write the
99    
100     \family typewriter
101     _self
102     \family default
103     methods incrementally, building on the already tested methods of previous
104     MODEL parts we are reusing.
105     In this way we never have to write a single huge method that directly manipulat
106     es the hundreds of variables that are in the model hierarchy.
107     Were that all there was to it, things would actually be pretty simple.
108     However, in ASCEND, one can also select to solve any part of an ASCEND
109     model (in particular, any part that is an instance of a single type), and
110     this capability complicates method writing - but not by much if we really
111     understand the approach we advocate here.
112     As an example, suppose we have a flowsheet that has a reactor followed
113     by a flash unit in it.
114     In ASCEND, we can select to solve the entire flowsheet, only the reactor,
115     only the flash unit or even any one of the streams in it (yes, each stream
116     has physical property calculations that belong to it making it interesting
117     to isolate and solve).
118     Should we choose to solve only the flash unit, ASCEND will isolate the
119     equations defining the flash - including the equations we use when defining
120     the input and output streams to it as they are a part of the flash unit.
121     But the input to the flash is also the output from the reactor and is a
122     part of the reactor, too.
123     Each part would typically take the prime responsibility for supplying methods
124     that will set fix flags, set nominal values, etc., for its variables, but
125     who owns the variables they both share such as in the connecting stream?
126     By
127     \begin_inset Quotes eld
128     \end_inset
129    
130     tradition
131     \begin_inset Quotes erd
132     \end_inset
133    
134     in chemical engineering flowsheet modeling, we will assert that the reactor
135     has prime responsibility for its output stream.
136     If we are solving the entire flowsheet, it should set the flags, etc., for
137     its output stream.
138     However, when we isolate the flash for solving, the flash unit must assume
139     responsibility to set fix flags, nominal values, etc., for the output stream
140     from the reactor as that stream is its input stream.
141     The
142     \family typewriter
143     _all
144     \family default
145     methods allow us to handle these shared variables correctly when we isolate
146     a part for solving by itself.
147     \begin_inset Note Note
148     status collapsed
149    
150     \begin_layout Standard
151     This needs more explanation: I don't find it completely clear.
152     \end_layout
153    
154     \end_inset
155    
156    
157     \end_layout
158    
159     \begin_layout Standard
160     Usually discovery of the information you need to write the methods proceeds
161     in the order that they appear below:
162     \family typewriter
163     check
164     \family default
165     ,
166     \family typewriter
167     default
168     \family default
169     ,
170     \family typewriter
171     specify
172     \family default
173     ,
174     \family typewriter
175     bound
176     \family default
177     ,
178     \family typewriter
179     scale
180     \family default
181     .
182    
183     \end_layout
184    
185     \begin_layout Section
186     Why use standardised methods on models?
187     \end_layout
188    
189     \begin_layout Standard
190     In the present chapter, we are proposing that you use a particular standardised
191     set of methods on your models.
192     While ASCEND doesn't force you to follow these conventions, we hope that
193     you will
194     \emph on
195     choose
196     \emph default
197     to follow them, because:
198     \end_layout
199    
200     \begin_layout Itemize
201     You models will be more portable.
202     \end_layout
203    
204     \begin_layout Itemize
205     They will integrate better with the existing model library when composing
206     larger models composed of smaller perhaps pre-existing models.
207     \end_layout
208    
209     \begin_layout Itemize
210     Other users will be be more easily able to understand what you have built.
211     \end_layout
212    
213     \begin_layout Itemize
214     The proposed structure has, in our experience, made for models that are
215     easier to debug.
216     \end_layout
217    
218     \begin_layout Standard
219     There will be cases where these standard methods don't suffice for your
220     needs; these are just proposals for a useful starting point and shared-use
221     conventions.
222     \end_layout
223    
224     \begin_layout Standard
225     Note that if you do not write the standard methods, your MODEL will inherit
226     the ones given in the library
227     \family typewriter
228     basemodel.a4l
229     \family default
230     .
231     The
232     \family typewriter
233     ClearAll
234     \family default
235     and
236     \family typewriter
237     reset
238     \family default
239     methods here will work for you if you follow the guidelines for the method
240    
241     \family typewriter
242     specify
243     \family default
244     .
245     The other methods defined in
246     \family typewriter
247     basemodel.a4l
248     \family default
249    
250     \family typewriter
251     (check_self
252     \family default
253     ,
254     \family typewriter
255     default_self
256     \family default
257     ,
258     \family typewriter
259     bound_self
260     \family default
261     ,
262     \family typewriter
263     scale_self
264     \family default
265     ,
266     \family typewriter
267     check_all
268     \family default
269     ,
270     \family typewriter
271     default_all
272     \family default
273     ,
274     \family typewriter
275     bound_all
276     \family default
277     ,
278     \family typewriter
279     scale_all
280     \family default
281     ) all contain
282     \family typewriter
283     STOP
284     \family default
285     statements that will warn you that you have skipped something important,
286     should you accidentally call one of these methods.
287     If you create a model for someone else and they run into one of these
288     \family typewriter
289     STOP
290     \family default
291     errors while using your model, that error is your fault.
292     \end_layout
293    
294     \begin_layout Section
295     Methods *_self
296     \begin_inset LatexCommand \index{methods, \_self}
297    
298     \end_inset
299    
300     VS *_all
301     \begin_inset LatexCommand \index{methods, \_all}
302    
303     \end_inset
304    
305    
306     \end_layout
307    
308     \begin_layout Standard
309     When you create a model definition, you create a container holding variables,
310     equations, arrays, and other models.
311     You create methods in the same definition to control the state of (the
312     values stored in) all these parts.
313     ASCEND lets you share objects among several models by passing objects through
314     a model interface (the
315     \family typewriter
316     MODEL
317     \family default
318     parameter list), by creating ALIASES
319     \begin_inset LatexCommand \index{ALIASES}
320    
321     \end_inset
322    
323     for parts within contained objects, and even by merging parts (though merging
324     should be avoided for any object larger than a variable).
325    
326     \end_layout
327    
328     \begin_layout Standard
329     \begin_inset Marginal
330     status collapsed
331    
332     \begin_layout Standard
333     Too many cooks
334     \begin_inset LatexCommand \index{cooks}
335    
336     \end_inset
337    
338     spoil the broth
339     \begin_inset LatexCommand \index{broth}
340    
341     \end_inset
342    
343     .
344     \end_layout
345    
346     \end_inset
347    
348     The problem this creates for you as a
349     \family typewriter
350     METHOD
351     \family default
352     writer is to decide which of the several
353     \family typewriter
354     MODEL
355     \family default
356     s that share an object is responsible for updating that variable's default,
357     bounds, and nominal values.
358     You could decide that every model which shares a variable is responsible
359     for these values.
360     This decision will lead to many, many, many hard to understand conflicts
361     as different models all try to manage the same value.
362     And, the last one run will in fact have the final say.
363     But it is difficult to know always which is the last one run.
364     The sensible approach is to make only one model responsible for the bounding,
365     scaling, and default setting of each variable:
366     \emph on
367     the model that creates the variable in the first place
368     \emph default
369     .
370     If you abide by this approach, you will keep things much simpler for yourself.
371     And, fortunately, the modeling language makes it pretty clear who has created
372     each and every variable - except when merging variables.
373     \end_layout
374    
375     \begin_layout Standard
376     \begin_inset Marginal
377     status collapsed
378    
379     \begin_layout Standard
380     Use *_self methods on locally created variables and parts
381     \end_layout
382    
383     \end_inset
384    
385     Consider the following model and creating the
386     \family typewriter
387     *_self
388     \family default
389     methods
390     \family typewriter
391     default_self
392     \family default
393     ,
394     \family typewriter
395     check_self
396     \family default
397     ,
398     \family typewriter
399     bound_self
400     \family default
401     , and
402     \family typewriter
403     scale_self
404     \family default
405     for it.
406    
407     \end_layout
408    
409     \begin_layout LyX-Code
410     MODEL selfish(
411     \end_layout
412    
413     \begin_layout LyX-Code
414     external_var WILL_BE solver_var;
415     \end_layout
416    
417     \begin_layout LyX-Code
418     out_thingy WILL_BE input_part;
419     \end_layout
420    
421     \begin_layout LyX-Code
422     );
423     \end_layout
424    
425     \begin_layout LyX-Code
426     my_variable IS_A solver_var;
427     \end_layout
428    
429     \begin_layout LyX-Code
430    
431     \end_layout
432    
433     \begin_layout LyX-Code
434     peek_at_variable ALIASES out_thingy.mabob.cost;
435     \end_layout
436    
437     \begin_layout LyX-Code
438     my_thingy IS_A nother_part;
439     \end_layout
440    
441     \begin_layout LyX-Code
442     navel_gaze ALIASES my_thingy.mabob.cost;
443     \end_layout
444    
445     \begin_layout LyX-Code
446     END selfish;
447     \end_layout
448    
449     \begin_layout Standard
450    
451     \end_layout
452    
453     \begin_layout Standard
454    
455     \family typewriter
456     IS_A
457     \family default
458     statements indicate all the parts we have created in this model: namely,
459     the
460     \family typewriter
461     solver_var
462     \family default
463     we call
464     \family typewriter
465     my_variable
466     \family default
467     and the
468     \family typewriter
469     nother_part
470     \family default
471     we call
472     \family typewriter
473     my_thingy
474     \family default
475     .
476     This model should manage the value of the only variable it creates:
477     \family typewriter
478     my_variable
479     \family default
480     .
481     The variable,
482     \family typewriter
483     external_var
484     \family default
485     , comes in from the outside so some other model has created it and should
486     manage it.
487     The variables
488     \family typewriter
489     peek_at_variable
490     \family default
491     and
492     \family typewriter
493     navel_gaze
494     \family default
495     also are not created here and should not be managed in the
496     \family typewriter
497     *_self
498     \family default
499     methods of
500     \family typewriter
501     selfish
502     \family default
503     .
504    
505     \family typewriter
506     my_thingy.mabob.cost
507     \family default
508     belongs to a part we created.
509     We want to default, bound, or scale variables in all parts we create, also,
510     so we must call
511     \family typewriter
512     my_thingy.default_self
513     \family default
514     whenever
515     \family typewriter
516     default_self
517     \family default
518     is called for this model.
519     Its
520     \family typewriter
521     *_self
522     \family default
523     method should in turn call the
524     \family typewriter
525     *_self
526     \family default
527     method for
528     \family typewriter
529     mabob
530     \family default
531     , which should set defaults, bounds and scaling for its variable,
532     \family typewriter
533     cost
534     \family default
535     .
536     Finally,
537     \family typewriter
538     out_thingy
539     \family default
540     is an input parameter and is not created here; we should not call
541     \family typewriter
542     out_thingy.default_self
543     \family default
544     , therefore, as some other model will do so.
545     \end_layout
546    
547     \begin_layout Standard
548     \begin_inset Marginal
549     status collapsed
550    
551     \begin_layout Standard
552     Use *_all methods to manage a troublesome part
553     \end_layout
554    
555     \end_inset
556    
557     As noted above, you may choose to isolate any mathematical subproblem in
558     a large simulation for debugging or solving purposes.
559     When you do this isolation using the Browser and Solver tools, you still
560     need to call scaling, bounding, and checking methods for all parts of the
561     isolated subproblem, even for those parts that come in from the outside.
562     This is easily done by writing
563     \family typewriter
564     *_all
565     \family default
566     methods.
567     In the example above,
568     \family typewriter
569     scale_all
570     \family default
571     will scale
572     \family typewriter
573     external_var
574     \family default
575     and call
576     \family typewriter
577     out_thingy.scale_all
578     \family default
579     because these parts are defined using
580     \family typewriter
581     WILL_BE
582     \family default
583    
584     \begin_inset LatexCommand \index{WILL\_BE}
585    
586     \end_inset
587    
588     statements.
589     Finally
590     \family typewriter
591     scale_all
592     \family default
593     will call its local
594     \family typewriter
595     *_self
596     \family default
597     to do all the normal scaling.
598     \end_layout
599    
600     \begin_layout Standard
601     That's the big picture of
602     \family typewriter
603     *_self
604     \family default
605     and
606     \family typewriter
607     *_all
608     \family default
609     methods.
610     Each kind of method (bound, scale, default, check) has its own peculiarities,
611     which we cover in Section
612     \begin_inset LatexCommand \ref{sec:methods.selfMethods}
613    
614     \end_inset
615    
616    
617     \noun off
618     and
619     \noun default
620     Section
621     \noun off
622    
623     \begin_inset LatexCommand \ref{sec:methods.allMethods}
624    
625     \end_inset
626    
627     , but they all follow the rules above
628     \noun default
629     and
630     \noun off
631     distinguish among variables and parts defined with
632     \family typewriter
633     \noun default
634     WILL_BE
635     \family default
636     \noun off
637     (managed in *
638     \family typewriter
639     \noun default
640     _all
641     \family default
642     \noun off
643     only), IS_A
644     \begin_inset LatexCommand \index{IS\_A}
645    
646     \end_inset
647    
648     (managed in
649     \family typewriter
650     \noun default
651     *_self
652     \family default
653     \noun off
654     only), and
655     \family typewriter
656     \noun default
657     ALIASES
658     \family default
659     \noun off
660     (not our responsibility).
661     \end_layout
662    
663     \begin_layout Section
664     How to write ClearAll
665     \begin_inset LatexCommand \index{ClearAll}
666    
667     \end_inset
668    
669     and reset
670     \begin_inset LatexCommand \index{reset}
671    
672     \end_inset
673    
674    
675     \end_layout
676    
677     \begin_layout Standard
678     Writing these two standard methods in your model is very simple: do nothing.
679     You may wish to write alternative
680     \family typewriter
681     reset_*
682     \family default
683     methods as we shall discuss.
684     All models inherit these methods from the definitions in
685     \family typewriter
686     basemodel.a4l
687     \family default
688     .
689     Just so you know, here is what they do.
690     \end_layout
691    
692     \begin_layout Subsection
693    
694     \family typewriter
695     METHOD ClearAll
696     \end_layout
697    
698     \begin_layout Standard
699     This method finds any variable that is a
700     \family typewriter
701     solver_var
702     \family default
703     or refinement of
704     \family typewriter
705     solver_var
706     \family default
707     and changes the
708     \family typewriter
709     .fixed
710     \family default
711     flag on that var to
712     \family typewriter
713     FALSE
714     \family default
715     .
716     This method only touches the
717     \family typewriter
718     .fixe
719     \family default
720     d flags; i.e., it does not change the value of
721     \family typewriter
722     .included
723     \family default
724     flags on relations or return boolean, integer and symbol variables to a
725     default value.
726    
727     \end_layout
728    
729     \begin_layout Subsection
730    
731     \family typewriter
732     METHOD reset
733     \end_layout
734    
735     \begin_layout Standard
736     This method calls
737     \family typewriter
738     ClearAll
739     \family default
740     to bring the model to a standard state with all variables unfixed (free),
741     then it calls the user-written specify method to bring the model to a state
742     where it has an equal number of variables to calculate and equations to
743     solve - i.e., to being
744     \begin_inset Quotes eld
745     \end_inset
746    
747     square.
748     \begin_inset Quotes erd
749     \end_inset
750    
751     Normally you do not need to write this method: your models will inherit
752     this one unless you override it (redefine it) in your model.
753     \end_layout
754    
755     \begin_layout Standard
756     This standard state is not necessarily the most useful starting state for
757     any particular application.
758     This method merely establishes a base case the modeler finds to be a good
759     starting point.
760     As an example, the modeler may elect to set fix variables for the base
761     case for a flash unit so it corresponds to an isothermal flash calculation.
762     Chemical engineers understand this case and can make changes from it to
763     set up other cases, such as an adiabatic flash, relatively easily by setting
764     and resetting but one or two
765     \family typewriter
766     .fixed
767     \family default
768     flags.
769     There is no one perfect "reset"' for all purposes.
770     Other
771     \family typewriter
772     reset_*
773     \family default
774     methods can also be written for particular purposes, if such arise
775     \begin_inset Foot
776     status collapsed
777    
778     \begin_layout Standard
779     The name of a method, for example
780     \family typewriter
781     reset_someOtherPurpose
782     \family default
783     is a communication tool.
784     Please use meaningful names as long as necessary to tell what the method
785     does.
786     Avoid cryptic abbreviations and hyper-specialized jargon known only to
787     you and your three friends when you are naming methods; however, do not
788     shy away from technical terms common to the engineering domain in which
789     you are modeling.
790     \end_layout
791    
792     \end_inset
793    
794     .
795     \end_layout
796    
797     \begin_layout Section
798     The
799     \family typewriter
800     *_self
801     \family default
802    
803     \begin_inset LatexCommand \index{\_self}
804    
805     \end_inset
806    
807     methods
808     \begin_inset LatexCommand \label{sec:methods.selfMethods}
809    
810     \end_inset
811    
812    
813     \end_layout
814    
815     \begin_layout Standard
816     The following methods should be redefined by each reusable library
817     \family typewriter
818     MODEL
819     \family default
820     .
821     Models that do not supply proper versions of these methods are usually
822     very hard to reuse.
823    
824     \end_layout
825    
826     \begin_layout Subsection
827    
828     \family typewriter
829     METHOD check_self
830     \family default
831    
832     \begin_inset LatexCommand \index{check\_self}
833    
834     \end_inset
835    
836    
837     \end_layout
838    
839     \begin_layout Standard
840     One can benefit by writing this method first, though it is run last.
841     Just as they taught you in elementary school, always check your work.
842     Start by defining criteria for a successful solution that will not be included
843     in the equations solved and compute them in this method.
844     As you develop your
845     \family typewriter
846     MODEL
847     \family default
848     , you should expect to revise the check method from time to time, if you
849     are learning anything about the model.
850     We frequently change our definition of success when modeling.
851     \end_layout
852    
853     \begin_layout Standard
854     When a mathematical model is solved, the assumptions that went into writing
855     (deriving) the equations should be checked.
856     Usually there are redundant equations available (more than one way to state
857     the physics or economics mathematically).
858     These should be used to check the particularly tricky bits of the model.
859     \end_layout
860    
861     \begin_layout Standard
862     Check that the physical or intuitive (qualitative) relationships among variables
863     you expect to hold are true, especially if you have not written such relationsh
864     ips in terms of inequalities (
865     \family typewriter
866     x*z <= y
867     \family default
868     ) in the
869     \family typewriter
870     MODEL
871     \family default
872     equations.
873     \end_layout
874    
875     \begin_layout Standard
876     In some models, checking the variable values against absolute physical limits
877     (
878     \family typewriter
879     temperature > 0{K}
880     \family default
881     and
882     \family typewriter
883     temperature < Tcritical
884     \family default
885     , for example) may be all that is necessary or possible.
886     Do not check variable values against their
887     \family typewriter
888     .lower_bound
889     \family default
890     or
891     \family typewriter
892     .upper_bound
893     \family default
894     , as ASCEND will do this for you.
895     \end_layout
896    
897     \begin_layout Standard
898     If a check fails, use a
899     \family typewriter
900     STOP
901     \family default
902    
903     \begin_inset LatexCommand \index{STOP}
904    
905     \end_inset
906    
907     statement to notify yourself (or your end-user) that the solution may be
908     bogus.
909    
910     \family typewriter
911     STOP
912     \family default
913     raises an error signal and issues an error message.
914    
915     \family typewriter
916     STOP
917     \family default
918     normally also stops further execution of the method and returns control
919     to a higher level, though there are interactive tools to force method execution
920     to continue.
921    
922     \family typewriter
923     STOP
924     \family default
925     does not cause ASCEND to exit though: just for the method execution to
926     halt and for control to return to the user.
927     \end_layout
928    
929     \begin_layout Subsection
930    
931     \family typewriter
932     METHOD default_self
933     \begin_inset LatexCommand \index{default\_self}
934    
935     \end_inset
936    
937    
938     \end_layout
939    
940     \begin_layout Standard
941     This method should set default values for any variables declared locally
942     (
943     \family typewriter
944     IS_A
945     \family default
946     ) to the model.
947     If the default value declared for the atom type, of which the variable
948     is an instance, is appropriate (and typically it is), then you need not
949     set a specific default value here.
950     This method also should run
951     \family typewriter
952     default_self
953     \family default
954     on all the complex parts that are declared locally (with
955     \family typewriter
956     IS_A
957     \family default
958     ) in the model.
959     \end_layout
960    
961     \begin_layout Standard
962     This method should not run any methods on model parts that come via
963     \family typewriter
964     WILL_BE
965     \family default
966     in the definition's parameter list.
967     This method also should not change the values of variables that are passed
968     in through the parameter list.
969     Sometimes there will be nothing for this method to do.
970     Define it anyway, leaving it empty, so that any writer reusing this model
971     as part of a higher level model can safely assume it is there and call
972     it without having to know the details.
973     \end_layout
974    
975     \begin_layout Standard
976     When a top-level simulation is built by the compiler, this method will be
977     run (for the top-level model) at the end of compilation.
978     If your model's
979     \family typewriter
980     default_self
981     \family default
982     method does not call the lower-level
983     \family typewriter
984     default_self
985     \family default
986     methods in your model locally-declared (
987     \family typewriter
988     IS_A
989     \family default
990     ) parts, it is quite likely that your model will not solve.
991     \end_layout
992    
993     \begin_layout Subsection
994    
995     \family typewriter
996     METHOD bound_self
997     \begin_inset LatexCommand \index{bound\_self}
998    
999     \end_inset
1000    
1001    
1002     \end_layout
1003    
1004     \begin_layout Standard
1005     Much of the art of nonlinear physical modeling is in bounding the solution.
1006     This method should update the bounds on locally defined (
1007     \family typewriter
1008     IS_A
1009     \family default
1010     ) variables and
1011     \family typewriter
1012     (IS_A)
1013     \family default
1014     defined model parts.
1015     Updating bounds requires some care.
1016     For example, the bounds on fractions frequently don't need updating.
1017     This method should not bound variables passed into the
1018     \family typewriter
1019     MODEL
1020     \family default
1021     definition or parts passed into the definition.
1022     \end_layout
1023    
1024     \begin_layout Standard
1025     A common formula for updating bounds is to define a region around the current
1026     value of the variable.
1027     A linear region size formula, as an example, would be:
1028     \end_layout
1029    
1030     \begin_layout Standard
1031     \begin_inset Formula \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