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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2785 - (hide annotations) (download) (as text)
Mon Jun 23 08:17:49 2014 UTC (4 years, 2 months ago) by jpye
File MIME type: application/x-lyx
File size: 31320 byte(s)
updating RPM spec for Fed20
1 jpye 2785 #LyX 2.1 created this file. For more info see http://www.lyx.org/
2     \lyxformat 474
3 johnpye 825 \begin_document
4     \begin_header
5     \textclass book
6 jpye 2785 \use_default_options false
7     \maintain_unincluded_children false
8 johnpye 825 \language english
9 jpye 2785 \language_package default
10 johnpye 825 \inputencoding auto
11 jpye 2785 \fontencoding global
12 jpye 1766 \font_roman default
13     \font_sans default
14     \font_typewriter default
15 jpye 2785 \font_math auto
16 jpye 1766 \font_default_family default
17 jpye 2785 \use_non_tex_fonts false
18 jpye 1766 \font_sc false
19     \font_osf false
20     \font_sf_scale 100
21     \font_tt_scale 100
22 johnpye 825 \graphics default
23 jpye 2785 \default_output_format default
24     \output_sync 0
25     \bibtex_command default
26     \index_command default
27 johnpye 825 \paperfontsize default
28     \spacing single
29 jpye 2785 \use_hyperref false
30 johnpye 825 \papersize a4paper
31     \use_geometry false
32 jpye 2785 \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 johnpye 825 \cite_engine basic
43 jpye 2785 \cite_engine_type default
44     \biblio_style plain
45 johnpye 825 \use_bibtopic false
46 jpye 2785 \use_indices false
47 johnpye 825 \paperorientation portrait
48 jpye 2785 \suppress_date false
49     \justification true
50     \use_refstyle 0
51     \index Index
52     \shortcut idx
53     \color #008000
54     \end_index
55 johnpye 825 \secnumdepth 3
56     \tocdepth 3
57     \paragraph_separation indent
58 jpye 2785 \paragraph_indentation default
59 johnpye 825 \quotes_language english
60     \papercolumns 1
61     \papersides 2
62     \paperpagestyle default
63     \tracking_changes false
64 jpye 1766 \output_changes false
65 jpye 2785 \html_math_output 0
66     \html_css_as_file 0
67     \html_be_strict false
68 johnpye 825 \end_header
69    
70     \begin_body
71    
72     \begin_layout Chapter
73     Defining Variables and Scaling Values
74 jpye 2785 \begin_inset CommandInset label
75     LatexCommand label
76 jpye 1766 name "cha:atoms"
77 johnpye 825
78     \end_inset
79    
80    
81     \end_layout
82    
83     \begin_layout Standard
84     \begin_inset Marginal
85     status collapsed
86    
87 jpye 2785 \begin_layout Plain Layout
88 johnpye 825 the purpose of this chapter
89     \end_layout
90    
91     \end_inset
92    
93 jpye 2785 By now you have probably read Chapter
94     \begin_inset space ~
95     \end_inset
96 johnpye 825
97 jpye 2785
98     \begin_inset CommandInset ref
99     LatexCommand vref
100 jpye 1766 reference "cha:model1"
101 johnpye 825
102     \end_inset
103    
104     and seen an example of how to create a model using existing variable types
105     in ASCEND.
106     You found that variables of types area, length, mass, mass_density, and
107     volume were needed and that they could be found in the library
108     \family typewriter
109     atoms.a4l
110     \family default
111     .
112     You want to know how to generalize on that; how to use variables, constants,
113     and scaling values in your own models so that the models will be easier
114     to solve.
115     \end_layout
116    
117     \begin_layout Standard
118     This chapter is meant to explain the following things:
119     \end_layout
120    
121     \begin_layout Itemize
122     The "Big Picture" of how variables, constants, and scaling values relate
123     to the rest of the ASCEND IV language and to equations in particular.
124     We'll keep it simple here.
125     More precise explanations for the language purist can be found in our syntax
126     document **syntax.fm5**.
127     You do not need to read about the "Big Picture" in order to read and use
128     the other parts of this chapter, but you may find it helpful if you are
129     having trouble writing an equation
130 jpye 2785 \begin_inset Index idx
131     status collapsed
132 johnpye 825
133 jpye 2785 \begin_layout Plain Layout
134     equation, writing
135     \end_layout
136    
137 johnpye 825 \end_inset
138    
139     so that ASCEND will accept it.
140     \end_layout
141    
142     \begin_layout Itemize
143     How to find the type of variable (or constant) you want.
144     We keep a mess of interesting
145     \family typewriter
146     ATOM
147     \family default
148     and
149     \family typewriter
150     CONSTANT
151     \family default
152     definitions in
153     \family typewriter
154     atoms.a4l
155     \family default
156     .
157     We provide tools to search in already loaded libraries to locate the type
158     you need.
159     \end_layout
160    
161     \begin_layout Itemize
162     How to define a new type of variable when we do not have a predefined
163     \family typewriter
164     ATOM
165     \family default
166     or
167     \family typewriter
168     CONSTANT
169     \family default
170     that suits your needs.
171     It is very easy to define your own variable types by copying code into
172     an atoms library of your own from
173     \family typewriter
174     atoms.a4l
175     \family default
176     and then editing the copied definition.
177     \end_layout
178    
179     \begin_layout Itemize
180     How to define a scaling variable to make your equations much easier to solve.
181     \end_layout
182    
183     \begin_layout Section
184     The Big Picture: a taxonomy
185 jpye 2785 \begin_inset Index idx
186     status collapsed
187 johnpye 825
188 jpye 2785 \begin_layout Plain Layout
189     taxonomy
190     \end_layout
191    
192 johnpye 825 \end_inset
193    
194    
195     \end_layout
196    
197     \begin_layout Standard
198 jpye 2785 As you read in Chapter
199     \begin_inset space ~
200     \end_inset
201 johnpye 825
202 jpye 2785
203     \begin_inset CommandInset ref
204     LatexCommand ref
205 jpye 1766 reference "cha:model1"
206 johnpye 825
207     \end_inset
208    
209     , simulations are built from MODEL and ATOM definitions, and MODEL and ATOM
210     definitions are defined by creating types in an ASCEND language text file
211     that you load into the ASCEND system.
212     Figure
213 jpye 2785 \begin_inset CommandInset ref
214     LatexCommand ref
215 jpye 1766 reference "fig:atoms.taxonomy"
216 johnpye 825
217     \end_inset
218    
219    
220     \noun off
221     shows the types of objects that can be defined.
222     You can see there are many more types than simply real variables used for
223     writing equations.
224     Some of these types can also be used in equations.
225     You also see that there are three kinds of equations, not simply real relations.
226     Throughout our documentation we call real relations simply "relations"
227     because that is the kind of equation most people are interested in most
228     of the time.
229     Notice that "scaling values" do not appear in this diagram.
230     We will cover scaling values at the end of this The major features of this
231     diagram are:
232     \end_layout
233    
234     \begin_layout Standard
235     \begin_inset Float figure
236     wide false
237     sideways false
238     status open
239    
240 jpye 2785 \begin_layout Plain Layout
241 jpye 1766 \align center
242 johnpye 825
243     \noun off
244     \begin_inset Graphics
245     filename howto-atomsFig1.eps
246     scale 90
247    
248     \end_inset
249    
250    
251     \end_layout
252    
253 jpye 2785 \begin_layout Plain Layout
254     \begin_inset Caption Standard
255 johnpye 825
256 jpye 2785 \begin_layout Plain Layout
257     \begin_inset CommandInset label
258     LatexCommand label
259 jpye 1766 name "fig:atoms.taxonomy"
260    
261 johnpye 825 \end_inset
262    
263     The big picture: how to think about variables
264     \end_layout
265    
266     \end_inset
267    
268    
269     \end_layout
270    
271 jpye 1766 \end_inset
272    
273    
274     \end_layout
275    
276 johnpye 825 \begin_layout Paragraph
277    
278     \noun off
279 jpye 2785 \begin_inset Index idx
280     status collapsed
281 johnpye 825
282 jpye 2785 \begin_layout Plain Layout
283     atom
284     \end_layout
285    
286 johnpye 825 \end_inset
287    
288    
289     \noun default
290     ATOM
291     \end_layout
292    
293     \begin_layout Itemize
294     Any variable quantity for use in relations, logical relations, or when statement
295     s or other computations.
296     These come in the usual programming language flavors real, boolean, symbol,
297     integer.
298     Not all kinds of atoms can be used in all kinds of equations, as we shall
299     explain when describing relations in a little bit.
300     Atoms may be assigned values many times interactively, with the Script
301     ASSIGN statement, with the METHOD := assignment operator, or by an ASCEND
302     client such as a solver.
303     \end_layout
304    
305     \begin_layout Standard
306     An ATOM may have attributes other than its value, such as .fixed in solver_var,
307     but these attributes are not atoms.
308     They are subatomic particles and cannot be used in equations.
309     These attributes are interpretable by ASCEND clients, and assignable by
310     the user in the same ways that the user assigns atom values.
311     \end_layout
312    
313     \begin_layout Standard
314     Each subatomic particle instance belongs to exactly one atom instance (one
315     variable in your compiled simulation).
316     This contrasts with an atom instance which can be shared among several
317     models by passing the atom instance from one model into another or by creating
318     aliases for it.
319     \end_layout
320    
321     \begin_layout Paragraph
322 jpye 2785 \begin_inset Index idx
323     status collapsed
324 johnpye 825
325 jpye 2785 \begin_layout Plain Layout
326     constant
327     \end_layout
328    
329 johnpye 825 \end_inset
330    
331     CONSTANT
332     \end_layout
333    
334     \begin_layout Itemize
335     Constants are "variables" that can be assigned no more than once.
336     By convention, all constant types in atoms.a4l have names that end in _constant
337     so that they are not easily confused with atoms.
338     A constant gets a values from the DEFAULT portion of its type definition,
339     by an interactive assignment, or by an assignment in the a model which
340     uses the :== assignment operator.
341     Constants cannot be assigned in a METHOD, nor can they be assigned with
342     the := operator.
343     \end_layout
344    
345     \begin_layout Standard
346     Integer and symbol constants can appear as members of sets or as subscripts
347     of arrays.
348     Integer, boolean, and symbol constants can be used to control SELECT statements
349     which determine your simulation's structure at compile-time or to control
350     SWITCH and WHEN behavior during problem solving .
351     \end_layout
352    
353     \begin_layout Paragraph
354 jpye 2785 \begin_inset Index idx
355     status collapsed
356 johnpye 825
357 jpye 2785 \begin_layout Plain Layout
358     set
359     \end_layout
360    
361 johnpye 825 \end_inset
362    
363     set
364     \end_layout
365    
366     \begin_layout Itemize
367     Sets are unordered lists of either integer or symbol constants.
368     A set is assigned its value exactly once.
369     The user interface always presents a set in sorted order, but this is for
370     convenience only.
371     Sets are useful for defining an array range or for writing indexed relations.
372     More about sets and their use can be found in **syntax.fm5**.
373     \end_layout
374    
375     \begin_layout Paragraph
376 jpye 2785 \begin_inset Index idx
377     status collapsed
378 johnpye 825
379 jpye 2785 \begin_layout Plain Layout
380     relationship
381     \end_layout
382    
383 johnpye 825 \end_inset
384    
385     relationships
386     \end_layout
387    
388     \begin_layout Itemize
389     Relations and logical relations allow you to state
390 jpye 2785 \begin_inset Index idx
391     status collapsed
392 johnpye 825
393 jpye 2785 \begin_layout Plain Layout
394     equalities
395     \end_layout
396    
397 johnpye 825 \end_inset
398    
399     equalities and
400 jpye 2785 \begin_inset Index idx
401     status collapsed
402 johnpye 825
403 jpye 2785 \begin_layout Plain Layout
404     inequalitites
405     \end_layout
406    
407 johnpye 825 \end_inset
408    
409     inequalities among the variables and constants in you models.
410     WHEN statements allow you to state relationships among the models and equations
411     which depend on the values of variables in those models.
412     Sets and symbols are not allowed in real or logical relations except when
413     used as array subscripts.
414     \end_layout
415    
416     \begin_layout Standard
417     Real
418 jpye 2785 \begin_inset Index idx
419     status collapsed
420 johnpye 825
421 jpye 2785 \begin_layout Plain Layout
422     real
423     \end_layout
424    
425 johnpye 825 \end_inset
426    
427    
428 jpye 2785 \begin_inset Index idx
429     status collapsed
430 johnpye 825
431 jpye 2785 \begin_layout Plain Layout
432     relation, real
433     \end_layout
434    
435 johnpye 825 \end_inset
436    
437     relations relate the values of real atoms, real constants, and integer constants.
438     Real relations cannot contain boolean constants and atoms, nor can they
439     contain integer atoms.
440    
441     \end_layout
442    
443     \begin_layout Standard
444     Logical
445 jpye 2785 \begin_inset Index idx
446     status collapsed
447 johnpye 825
448 jpye 2785 \begin_layout Plain Layout
449     logical
450     \end_layout
451    
452 johnpye 825 \end_inset
453    
454     relations
455 jpye 2785 \begin_inset Index idx
456     status collapsed
457 johnpye 825
458 jpye 2785 \begin_layout Plain Layout
459     logical relation
460     \end_layout
461    
462 johnpye 825 \end_inset
463    
464     relate the values of boolean atoms and boolean constants.
465     The
466     \family typewriter
467     SATISFIED
468     \family default
469    
470 jpye 2785 \begin_inset Index idx
471     status collapsed
472 johnpye 825
473 jpye 2785 \begin_layout Plain Layout
474     SATISFIED
475     \end_layout
476    
477 johnpye 825 \end_inset
478    
479     operator makes it possible to include real relations in a logical relation.
480     Neither integer atoms and constants nor real atoms and constants are allowed
481     in logical relations.
482     If you find yourself trying to write an equation with integer atoms, you
483     are really creating a conditional model for which you should use the WHEN
484     statement instead.
485     See **conditional modeling** to learn about how ASCEND represents this
486     kind of mathematical model.
487     There are also a real variable types, solver_integer and solver_binary,
488     which are used to formulate equations when the solver is expected to initially
489     treat the variable as a real value but drive it to an integer or 0-1 value
490     at the solution.
491     The integer programming features of ASCEND are described **elsewhere**.
492     \end_layout
493    
494     \begin_layout Standard
495     Like atoms, real and logical relations may have attributes, subatomic particles
496     for use by ASCEND clients and users.
497     The name of a relation can be used in writing logical relations and WHEN
498     statements.
499    
500     \end_layout
501    
502     \begin_layout Standard
503     WHEN statements are outside the scope of this chapter; please see **conditional
504     modeling** or **syntax.fm5** for the details.
505     \end_layout
506    
507     \begin_layout Paragraph
508 jpye 2785 \begin_inset Index idx
509     status collapsed
510 johnpye 825
511 jpye 2785 \begin_layout Plain Layout
512     model
513     \end_layout
514    
515 johnpye 825 \end_inset
516    
517    
518     \family typewriter
519     MODEL
520     \end_layout
521    
522     \begin_layout Itemize
523     A model is simply a container for a collection of atoms, constants, sets,
524     relations, logical relations, when statements, and arrays of any of these.
525     The container also specifies some of the methods that can be used to manipulate
526     its contents.
527     Compiling a model creates an instance of it-- a simulation
528 jpye 2785 \begin_inset Index idx
529     status collapsed
530 johnpye 825
531 jpye 2785 \begin_layout Plain Layout
532     simulation
533     \end_layout
534    
535 johnpye 825 \end_inset
536    
537     .
538     \end_layout
539    
540     \begin_layout Paragraph
541    
542     \family typewriter
543     SOLVER_VAR
544     \end_layout
545    
546     \begin_layout Itemize
547     The real atom type
548     \family typewriter
549     solver_var
550     \family default
551     is the type from which all real variables that you want the system to solve
552     for must spring.
553     If you define a real variable using a type which is not a refinement of
554    
555     \family typewriter
556     solver_var
557     \family default
558     , all solvers will treat that variable as an a scaling value or other given
559     constant rather than as a variable.
560    
561     \end_layout
562    
563     \begin_layout Standard
564     Solver_vars have a number of subatomic attributes (
565     \family typewriter
566     upper_bound
567     \family default
568     ,
569     \family typewriter
570     lower_bound
571     \family default
572     , and so forth) that help solvers find the solution of your model.
573     ATOM definitions specify appropriate default values for these attributes
574     that depend on the expected applications of the atom.
575     These attribute values can (and should) be modified by methods in the final
576     application model where the most accurate problem information is available.
577     \end_layout
578    
579     \begin_layout Paragraph
580     Scaling
581 jpye 2785 \begin_inset Index idx
582     status collapsed
583 johnpye 825
584 jpye 2785 \begin_layout Plain Layout
585     scaling
586     \end_layout
587    
588 johnpye 825 \end_inset
589    
590     value
591     \end_layout
592    
593     \begin_layout Itemize
594     A real that is not a member of the
595     \family typewriter
596     solver_var
597     \family default
598     family is ignored by the solver.
599     Numerical solvers for problems with many equations in many variables work
600     better if the error computed for each equation (before the system is solved)
601     is of approximately size 1.0.
602     This is most critical when you are starting to solve a new problem at values
603     far, far away from the solution.
604     When the error of one equation is much larger than the errors in the others,
605     that error will skew the behavior of most numerical solvers and will cause
606     poor performance.
607    
608     \end_layout
609    
610     \begin_layout Standard
611     This is one of the many reasons that scientists and engineers work with
612     dimensionless models
613 jpye 2785 \begin_inset Index idx
614     status collapsed
615 johnpye 825
616 jpye 2785 \begin_layout Plain Layout
617     dimensionless models
618     \end_layout
619    
620 johnpye 825 \end_inset
621    
622     : the process of scaling the equations into dimensionless form has the effect
623     of making the error of each equation roughly the same size even far away
624     from the solution.
625     It is sometimes easiest to obtain a dimensionless equation by writing the
626     equation in its dimensional form using natural variables and then dividing
627     both sides by an appropriate scaling value.
628     We will see how to define an atom for scaling purposes in the last part
629     of this chapter.
630     \end_layout
631    
632     \begin_layout Section
633     How to find the right variable type
634 jpye 2785 \begin_inset Index idx
635     status collapsed
636 johnpye 825
637 jpye 2785 \begin_layout Plain Layout
638     type, variable
639     \end_layout
640    
641 johnpye 825 \end_inset
642    
643    
644     \end_layout
645    
646     \begin_layout Standard
647     The type of real atom you want to use depends first on the dimensionality
648     (length, mass/time, etc.) needed and then on the application in which the
649     atom is going to be used.
650     For example, if you are modeling a moving car and you want an atom type
651     to describe the car's speed, then you need to find an atom with dimensionality
652     length/time or in ASCEND terms L/T.
653     There may be two or three types with this dimensionality, possibly including
654     real_constants, a real scaling value, and an atom derived from solver_var.
655     \end_layout
656    
657     \begin_layout Standard
658     \begin_inset Marginal
659     status collapsed
660    
661 jpye 2785 \begin_layout Plain Layout
662 johnpye 825 Load atoms.a4l
663     \end_layout
664    
665     \end_inset
666    
667     The first step to finding the variable type needed is to make sure that
668     atoms.a4l is loaded in your Library window from
669     \family typewriter
670     ascend4/models/atoms.a4l
671     \family default
672     .
673     \end_layout
674    
675     \begin_layout Standard
676     \begin_inset Marginal
677     status collapsed
678    
679 jpye 2785 \begin_layout Plain Layout
680 johnpye 825 Find an ATOM or CONSTANT by units
681     \end_layout
682    
683     \end_inset
684    
685     The next step is to open the "ATOM by units" dialog found in the Library
686     window's Find menu.
687     This dialog asks for the units of the real variable type you want.
688     For our example, speed, you would enter "feet/second," "furlongs/fortnight,"
689     "meter^3/second/ft^2" or any other combination of units that corresponds
690     to the dimensionality L/T.
691    
692     \end_layout
693    
694     \begin_layout Standard
695     If the system is able to deduce the dimensionality of the units you have
696     entered, it will return a list of all the currently loaded ATOM and CONSTANT
697     definitions with matching dimensions.
698     It may fail to understand the units, in which case you should try the correspon
699     ding SI units.
700     If it understands the units but there are no matching atoms or constants,
701     you will be duly informed.
702     If there is no atom that meets your needs, you should create one as outlined
703     in **the next section**.
704     \end_layout
705    
706     \begin_layout Standard
707     \begin_inset Marginal
708     status collapsed
709    
710 jpye 2785 \begin_layout Plain Layout
711 johnpye 825 Selecting the right type
712     \end_layout
713    
714     \end_inset
715    
716     The resulting list of types includes a Code button which will display the
717     definition of any of the types listed once you select (highlight) that
718     type with the mouse.
719     Usually you will need to examine several of the alternatives to see which
720     one is most appropriate to the physics and mathematics of your problem.
721     Compare the default, bounds, and nominal values defined to those you need.
722     Check whether the type you are looking at is a
723     \family typewriter
724     CONSTANT
725     \family default
726     or an
727     \family typewriter
728     ATOM
729     \family default
730     .
731    
732     \end_layout
733    
734     \begin_layout Standard
735     You now know the name of the variable type you need, or you know that you
736     must create a new one to suit your needs.
737     \end_layout
738    
739     \begin_layout Section
740     How to define a new type of variable
741 jpye 2785 \begin_inset Index idx
742     status collapsed
743 johnpye 825
744 jpye 2785 \begin_layout Plain Layout
745     type, variable
746     \end_layout
747    
748 johnpye 825 \end_inset
749    
750    
751 jpye 2785 \begin_inset CommandInset label
752     LatexCommand label
753 jpye 1766 name "ssec:atoms.newVarType"
754 johnpye 825
755     \end_inset
756    
757    
758     \end_layout
759    
760     \begin_layout Standard
761     In this section we will give examples of defining the atom and constant
762     types as well as outline a few exceptional situations when you should NOT
763     define a new type.
764     More examples can be found and copied from
765     \family typewriter
766     atoms.a4l
767     \family default
768     .
769     You should define your new atoms in your personal atoms library.
770    
771     \end_layout
772    
773     \begin_layout Standard
774     \begin_inset Marginal
775     status collapsed
776    
777 jpye 2785 \begin_layout Plain Layout
778 johnpye 825 Saving customized variable types
779     \end_layout
780    
781     \end_inset
782    
783     The user data file
784     \family typewriter
785     ~
786     \backslash
787     ascdata
788     \backslash
789     myatoms.a4l
790     \family default
791     is the normal location for a personal
792 jpye 2785 \begin_inset Index idx
793     status collapsed
794 johnpye 825
795 jpye 2785 \begin_layout Plain Layout
796     library, personal
797     \end_layout
798    
799 johnpye 825 \end_inset
800    
801     library.
802     This file contains the following three lines and then the
803     \family typewriter
804     ATOM
805     \family default
806     and
807     \family typewriter
808     CONSTANT
809     \family default
810     definitions you create.
811     \end_layout
812    
813     \begin_layout LyX-Code
814     REQUIRE "atoms.a4l"; (* loads our atoms first *)
815     \end_layout
816    
817     \begin_layout LyX-Code
818     PROVIDE "myatoms.a4l"; (* registers your library *)
819     \end_layout
820    
821     \begin_layout LyX-Code
822     (* Custom atoms created by <insert your name here> *)
823     \end_layout
824    
825     \begin_layout Standard
826     If you develop an interesting set of atoms for some problem domain outside
827     chemical engineering thermodynamics, please consider mailing it to us through
828     our web page.
829    
830     \end_layout
831    
832     \begin_layout Standard
833     The user data directory
834     \family typewriter
835     ~/
836 jpye 2785 \begin_inset Index idx
837     status collapsed
838 johnpye 825
839 jpye 2785 \begin_layout Plain Layout
840     ascdata
841     \end_layout
842    
843 johnpye 825 \end_inset
844    
845     ascdata
846     \family default
847     may have a different name if you are running under Windows and do not have
848     the environment variable HOME
849 jpye 2785 \begin_inset Index idx
850     status collapsed
851 johnpye 825
852 jpye 2785 \begin_layout Plain Layout
853     HOME
854     \end_layout
855    
856 johnpye 825 \end_inset
857    
858     defined.
859     It may be something like C:
860     \backslash
861     ascdata or
862     \backslash
863     WINNT
864     \backslash
865     Profiles
866     \backslash
867     Your Name
868     \backslash
869     ascdata.
870     When ASCEND is started, it prints out the name of this directory.
871     \end_layout
872    
873     \begin_layout Standard
874     When you write a
875     \family typewriter
876     MODEL
877     \family default
878     which depends on the definition of your new atoms, do not forget to add
879     the statement
880     \end_layout
881    
882     \begin_layout LyX-Code
883     REQUIRE "myatoms.a4l";
884     \end_layout
885    
886     \begin_layout Standard
887     at the very top of your model file so that your atoms will be loaded before
888     your model definitions try to use them.
889     \end_layout
890    
891     \begin_layout Subsection
892     A new real variable for solver use
893     \end_layout
894    
895     \begin_layout Standard
896     Suppose you need an atom with units {dollar/ft^2/year} for some equation
897     relating amortized construction costs to building size.
898     Maybe this example is a bit far fetched, but it is a safe bet that our
899     library is not going to have an atom or a constant for these units.
900     Here is the standard incantation for defining a new variable type based
901     on
902     \family typewriter
903     solver_var
904     \family default
905     .
906     ASCEND allows a few permutations on this incantation, but they are of no
907     practical value.
908     The parts of this incantation that are in italics should be changed to
909     match your needs.
910     You can skip the comments, but you
911     \emph on
912     must
913     \emph default
914     include the units of the default on the bounds and nominal.
915     \end_layout
916    
917     \begin_layout LyX-Code
918     ATOM amortized_area_cost
919     \end_layout
920    
921     \begin_layout LyX-Code
922     REFINES solver_var DEFAULT 3.0 {dollar/ft^2/year};
923     \end_layout
924    
925     \begin_layout LyX-Code
926     lower_bound := 0 {dollar/ft^2/year};
927     \end_layout
928    
929     \begin_layout LyX-Code
930     (* minimum value *)
931     \end_layout
932    
933     \begin_layout LyX-Code
934     upper_bound := 10000 {dollar/ft^2/year};
935     \end_layout
936    
937     \begin_layout LyX-Code
938     (* maximum value for any sane application *)
939     \end_layout
940    
941     \begin_layout LyX-Code
942     nominal := 10 {dollar/ft^2/year};
943     \end_layout
944    
945     \begin_layout LyX-Code
946     (* expected size for all reasonable applications*)
947     \end_layout
948    
949     \begin_layout LyX-Code
950     END amortized_area_cost;
951     \end_layout
952    
953     \begin_layout Standard
954     In picking the name of your atom, remember that names should be as self-explanat
955     ory as possible.
956     Also avoid choosing a name that ends in _constant (as this is conventionally
957     applied only to CONSTANT
958 jpye 2785 \begin_inset Index idx
959     status collapsed
960 johnpye 825
961 jpye 2785 \begin_layout Plain Layout
962     CONSTANT
963     \end_layout
964    
965 johnpye 825 \end_inset
966    
967     definitions) or _parameter.
968     Parameter is an extremely ambiguous and therefore useless word.
969     Also remember that the role a variable plays in solving a set of equations
970     depends on how the solver being applied interprets .fixed and other attributes
971     of the variable.
972     \end_layout
973    
974     \begin_layout Standard
975     \begin_inset Marginal
976     status collapsed
977    
978 jpye 2785 \begin_layout Plain Layout
979 johnpye 825 Exceptions
980     \end_layout
981    
982     \end_inset
983    
984     If an atom type matches all but one of the attributes you need for your
985     problem, say for example the
986     \family typewriter
987     upper_bound
988     \family default
989     is way too high, use the existing variable type and reassign the bound
990     to a more sensible value in the
991     \family typewriter
992     default_self
993     \family default
994     method of the model where the variable is created.
995     Having a dozen atoms defined for the same units gets confusing in short
996     order to anyone you might share your models with.
997     \end_layout
998    
999     \begin_layout Standard
1000     The exception to the exception (yes, there always seems to be one of those)
1001     is the case of a
1002     \family typewriter
1003     lower_bound
1004     \family default
1005     set at zero.
1006     Usually a
1007     \family typewriter
1008     lower_bound
1009     \family default
1010     of zero indicates that there is something inherently positive about variables
1011     of that type.
1012     Variables with a bound of this type should not have these physical bounds
1013     expanded in an application.
1014     Another example of this type of bound is the
1015     \family typewriter
1016     upper_bound
1017     \family default
1018     1.0 on the type fraction.
1019     \end_layout
1020    
1021     \begin_layout Standard
1022     For example, negative temperature just is not sensible for most physical
1023     systems.
1024     ASCEND defines a temperature atom for use in equations involving the absolute
1025     temperature.
1026     On the other hand, a temperature difference, delta T, is frequently negative
1027     so a separate atom is defined.
1028     Anyone receiving a model written using the two types of atoms, which both
1029     have units of {Kelvin}, can easily tell which variables might legitimately
1030     take on negative values by noting whether the variable is defined as a
1031     temperature or a delta_temperature.
1032     \end_layout
1033    
1034     \begin_layout Subsection
1035     A new real constant
1036 jpye 2785 \begin_inset Index idx
1037     status collapsed
1038 johnpye 825
1039 jpye 2785 \begin_layout Plain Layout
1040     real constant
1041     \end_layout
1042    
1043 johnpye 825 \end_inset
1044    
1045    
1046 jpye 2785 \begin_inset Index idx
1047     status collapsed
1048 johnpye 825
1049 jpye 2785 \begin_layout Plain Layout
1050     constant, real
1051     \end_layout
1052    
1053 johnpye 825 \end_inset
1054    
1055     type
1056     \end_layout
1057    
1058     \begin_layout Standard
1059     Real constants which do not have a default value are usually needed only
1060     in libraries of reusable models, such as
1061     \family typewriter
1062     components.a4l
1063     \family default
1064     , where the values depend on the end-user's selection from alternatives
1065     in a database.
1066     The standard incantation to define a new real constant type is:
1067     \end_layout
1068    
1069     \begin_layout LyX-Code
1070     CONSTANT
1071     \shape italic
1072     critical_pressure_constant
1073     \end_layout
1074    
1075     \begin_layout LyX-Code
1076     REFINES real_constant DIMENSION
1077     \shape italic
1078     M/L/T^2
1079     \shape default
1080     ;
1081     \end_layout
1082    
1083     \begin_layout Standard
1084     Here again, the italic parts of this incantation should be redefined for
1085     your purpose.
1086     \end_layout
1087    
1088     \begin_layout Standard
1089     \begin_inset Marginal
1090     status collapsed
1091    
1092 jpye 2785 \begin_layout Plain Layout
1093 johnpye 825 Universal exceptions and unit conversions
1094     \end_layout
1095    
1096     \end_inset
1097    
1098     It is wasteful to define a
1099     \family typewriter
1100     CONSTANT
1101     \family default
1102     type and a compiled object to represent a universal
1103 jpye 2785 \begin_inset Index idx
1104     status collapsed
1105 johnpye 825
1106 jpye 2785 \begin_layout Plain Layout
1107     universal constant
1108     \end_layout
1109    
1110 johnpye 825 \end_inset
1111    
1112    
1113 jpye 2785 \begin_inset Index idx
1114     status collapsed
1115 johnpye 825
1116 jpye 2785 \begin_layout Plain Layout
1117     constant, universal
1118     \end_layout
1119    
1120 johnpye 825 \end_inset
1121    
1122     constant.
1123     For example, the thermodynamic gas constant, R = 8.314...
1124     {J/mole/K}, is frequently needed in modeling chemical systems.
1125     The SI value of R does not vary with its application.
1126     Neither does the value of
1127 jpye 2785 \begin_inset Index idx
1128     status collapsed
1129 johnpye 825
1130 jpye 2785 \begin_layout Plain Layout
1131     pi
1132     \end_layout
1133    
1134 johnpye 825 \end_inset
1135    
1136    
1137     \begin_inset Formula $\pi$
1138     \end_inset
1139    
1140     .
1141     Numeric constants of this sort are better represented as a numeric coefficient
1142     and an appropriately defined unit conversion.
1143     Consider the
1144 jpye 2785 \begin_inset Index idx
1145     status collapsed
1146 johnpye 825
1147 jpye 2785 \begin_layout Plain Layout
1148     ideal gas law
1149     \end_layout
1150    
1151 johnpye 825 \end_inset
1152    
1153     ideal gas law, PV = NRT and the ASCEND unit conversion {GAS_C} which appears
1154     in the library ascend4/models/measures.a4l.
1155     This equation should be written:
1156     \end_layout
1157    
1158     \begin_layout LyX-Code
1159     P * V = n * 1.0{GAS_C} * T;
1160     \end_layout
1161    
1162     \begin_layout Standard
1163     Similarly, area = pi*r^2 should be written
1164     \end_layout
1165    
1166     \begin_layout LyX-Code
1167     area = 1{PI} * r^2;
1168     \end_layout
1169    
1170     \begin_layout Standard
1171     The coefficient 1 of
1172     \family typewriter
1173     {GAS_C}
1174     \family default
1175     and {PI} in these equations takes of the dimensionality of and is multiplied
1176     by the conversion factor implied by the
1177     \family typewriter
1178     UNITS
1179     \family default
1180     definition for the units.
1181     If we check
1182     \family typewriter
1183     measures.a4l
1184     \family default
1185     , we find the definition of PI is simply {3.14159...} and the definition of
1186    
1187     \family typewriter
1188     GAS_C
1189     \family default
1190     is {8.314...
1191     J/mole/K} as we ought to expect.
1192     \end_layout
1193    
1194     \begin_layout Standard
1195     For historical reasons there are a few universal constant definitions in
1196    
1197     \family typewriter
1198     atoms.a4l
1199     \family default
1200     .
1201     New modelers should not use them; they are only provided to support outdated
1202     models that no one has yet taken the time to update.
1203     \end_layout
1204    
1205     \begin_layout Subsection
1206     New types for integers, symbols, and booleans
1207     \end_layout
1208    
1209     \begin_layout Standard
1210     The syntax for
1211     \family typewriter
1212     ATOM
1213     \family default
1214     and
1215     \family typewriter
1216     CONSTANT
1217     \family default
1218     definitions of the non-real types is the same as for real number types,
1219     except that units are not involved.
1220     Take your best guess based on the examples above, and you will get it right.
1221     If even that is too hard, more details are given in **syntax.fm5**.
1222     \end_layout
1223    
1224     \begin_layout Section
1225     How to define a
1226 jpye 2785 \begin_inset Index idx
1227     status collapsed
1228 johnpye 825
1229 jpye 2785 \begin_layout Plain Layout
1230     scaling
1231     \end_layout
1232    
1233 johnpye 825 \end_inset
1234    
1235     scaling variable
1236     \end_layout
1237    
1238     \begin_layout Standard
1239     A scaling variable
1240     \family typewriter
1241     ATOM
1242     \family default
1243     is defined with a name that ends in _scale as follows.
1244     Note that this
1245     \family typewriter
1246     ATOM
1247     \family default
1248     does not refine
1249     \family typewriter
1250     solver_var
1251     \family default
1252     , so solvers will not try to change variables of this type during the solution
1253     process.
1254     \end_layout
1255    
1256     \begin_layout LyX-Code
1257     ATOM distance_scale REFINES real DEFAULT 1.0{meter};
1258     \end_layout
1259    
1260     \begin_layout LyX-Code
1261     END distance_scale;
1262     \end_layout
1263    
1264     \begin_layout Standard
1265     \begin_inset Marginal
1266     status collapsed
1267    
1268 jpye 2785 \begin_layout Plain Layout
1269 johnpye 825 ASCEND cannot do it all for you
1270     \end_layout
1271    
1272     \end_inset
1273    
1274     ASCEND uses a combination of symbolic and numerical techniques to create
1275     and solve mathematical problems.
1276     Once you get the problem close to the solution, ASCEND can internally compute
1277     its own scaling values for relations, known elsewhere as "relation nominals
1278 jpye 2785 \begin_inset Index idx
1279     status collapsed
1280 johnpye 825
1281 jpye 2785 \begin_layout Plain Layout
1282     nominals
1283     \end_layout
1284    
1285 johnpye 825 \end_inset
1286    
1287     ,
1288     \begin_inset Quotes erd
1289     \end_inset
1290    
1291     assuming you have set good values for the .nominal attribute of all the
1292     variables.
1293     It does this by computing the largest additive term in each equation.
1294     The absolute value of this term is a very good scaling value.
1295     \end_layout
1296    
1297     \begin_layout Standard
1298     This internal scaling works quite well, but not when the problem is very
1299     far away from the solution so that the largest additive terms computed
1300     are not at all representative of the physical situation being modeled.
1301     The
1302     \family typewriter
1303     scale_self
1304     \family default
1305    
1306 jpye 2785 \begin_inset Index idx
1307     status collapsed
1308 johnpye 825
1309 jpye 2785 \begin_layout Plain Layout
1310     scale
1311     \begin_inset ERT
1312     status collapsed
1313    
1314     \begin_layout Plain Layout
1315    
1316    
1317     \backslash
1318     _
1319     \end_layout
1320    
1321 johnpye 825 \end_inset
1322    
1323 jpye 2785 self
1324     \end_layout
1325 johnpye 825
1326 jpye 2785 \end_inset
1327    
1328     method, which should be written for every model as described in Section
1329     \begin_inset space ~
1330     \end_inset
1331    
1332    
1333     \begin_inset CommandInset ref
1334     LatexCommand ref
1335 jpye 1766 reference "sssec:methods.scaleself"
1336 johnpye 825
1337     \end_inset
1338    
1339     of Chapter
1340     \noun off
1341    
1342 jpye 2785 \begin_inset space ~
1343     \end_inset
1344    
1345    
1346     \begin_inset CommandInset ref
1347     LatexCommand vref
1348 jpye 1766 reference "cha:methods"
1349 johnpye 825
1350     \end_inset
1351    
1352     should set the equation scaling values you have defined in a
1353     \family typewriter
1354     \noun default
1355     MODEL
1356     \family default
1357     \noun off
1358     based on the best available information.
1359     In a chemical engineering flowsheeting problem, for example, information
1360     about a key process material flow should be propagated throughout the process
1361     flowsheet to scale all the other flows, material balance equations, and
1362     energy balance equations.
1363     \end_layout
1364    
1365     \begin_layout Standard
1366     \begin_inset Marginal
1367     status collapsed
1368    
1369 jpye 2785 \begin_layout Plain Layout
1370 johnpye 825 Scaling atom default value
1371     \end_layout
1372    
1373     \end_inset
1374    
1375     The
1376 jpye 2785 \begin_inset Index idx
1377     status collapsed
1378 johnpye 825
1379 jpye 2785 \begin_layout Plain Layout
1380     default value
1381     \end_layout
1382    
1383 johnpye 825 \end_inset
1384    
1385     default value for any scaling atom should always be 1.0 in appropriate SI
1386     units, so that the scaling will have no effect until you assign a problem
1387     specific value.
1388     Multiplying or dividing both sides of an equation by 1.0 obviously will
1389     not change the mathematical behavior, but you do not want to change the
1390     behavior arbitrarily either-- you want to change it based on problem informatio
1391     n that is not contained in your
1392     \family typewriter
1393     myatoms.a4l
1394     \family default
1395     file.
1396     \end_layout
1397    
1398     \end_body
1399     \end_document

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