/[ascend]/trunk/doc/syntax.lyx
ViewVC logotype

Annotation of /trunk/doc/syntax.lyx

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1733 - (hide annotations) (download) (as text)
Wed Feb 6 00:18:31 2008 UTC (16 years, 5 months ago) by jpye
File MIME type: application/x-lyx
File size: 179854 byte(s)
In process of moving DOPRI5 solver to 'solvers' dir.
1 jpye 1733 #LyX 1.5.1 created this file. For more info see http://www.lyx.org/
2     \lyxformat 276
3 johnpye 828 \begin_document
4     \begin_header
5     \textclass book
6     \begin_preamble
7     \usepackage[bookmarks]{hyperref}
8     \usepackage{lmodern}
9     \end_preamble
10     \language english
11     \inputencoding auto
12 jpye 1733 \font_roman default
13     \font_sans default
14     \font_typewriter default
15     \font_default_family default
16     \font_sc false
17     \font_osf false
18     \font_sf_scale 100
19     \font_tt_scale 100
20 johnpye 828 \graphics default
21     \paperfontsize default
22     \spacing single
23     \papersize default
24     \use_geometry false
25     \use_amsmath 1
26 jpye 1733 \use_esint 0
27 johnpye 828 \cite_engine basic
28     \use_bibtopic false
29     \paperorientation portrait
30     \secnumdepth 3
31     \tocdepth 3
32     \paragraph_separation indent
33     \defskip medskip
34     \quotes_language english
35     \papercolumns 1
36     \papersides 1
37     \paperpagestyle default
38     \tracking_changes false
39     \output_changes false
40 jpye 1733 \author ""
41 johnpye 828 \end_header
42    
43     \begin_body
44    
45     \begin_layout Chapter
46 jpye 1384 Syntax reference
47 jpye 1733 \begin_inset LatexCommand label
48     name "cha:ASCENDSyntax"
49 johnpye 828
50     \end_inset
51    
52    
53     \end_layout
54    
55     \begin_layout Standard
56     We shall present an informal description of the ASCEND IV language.
57     Being informal, we shall usually include examples and descriptions of the
58     intended semantics along with the syntax of the items.
59     At times the inclusion of semantics will seem to anticipate later definitions.
60     We do this because we would also like this chapter to be used as a reference
61     for the ASCEND language even after one generally understands it.
62     Often one will need to clarify a point about a particular item and will
63     not wish to have to search in several places to do so.
64     \end_layout
65    
66     \begin_layout Standard
67     Syntax
68 jpye 1733 \begin_inset LatexCommand index
69     name "syntax"
70 johnpye 828
71     \end_inset
72    
73     is the form or structure for the statements in ASCEND, where one worries
74     about the exact words one uses, their ordering, the punctuation, etc.
75     Semantics
76 jpye 1733 \begin_inset LatexCommand index
77     name "semantics"
78 johnpye 828
79     \end_inset
80    
81     describe the meaning of a statement.
82     \end_layout
83    
84     \begin_layout Standard
85     To distinguish between syntax and semantics, consider the statement
86     \end_layout
87    
88     \begin_layout LyX-Code
89     y IS_A fraction;
90     \end_layout
91    
92     \begin_layout Standard
93     Rules on the syntax for this statement tell us we need a user supplied instance
94     name, y, followed by the ASCEND operator IS_A, followed by a type name
95     (fraction).
96     The statement terminates with a semicolon.
97     The statement semantics says we are declaring the existence of an instance,
98     locally named y, of the type fraction as a part within the current model
99     definition and it is to be constructed when an instance of the current
100     model definition is constructed.
101     \end_layout
102    
103     \begin_layout Standard
104     The syntax for a computer language is often defined by using a Bachus-Naur
105 jpye 1733 \begin_inset LatexCommand index
106     name "Bachus-Naur"
107 johnpye 828
108     \end_inset
109    
110     formal (BNF
111 jpye 1733 \begin_inset LatexCommand index
112     name "BNF"
113 johnpye 828
114     \end_inset
115    
116     ) description.
117     The complete YACC
118 jpye 1733 \begin_inset LatexCommand index
119     name "YACC"
120 johnpye 828
121     \end_inset
122    
123     and FLEX
124 jpye 1733 \begin_inset LatexCommand index
125     name "FLEX"
126 johnpye 828
127     \end_inset
128    
129     description of the language described (as presently implemented) is available
130     by FTP and via the World Wide Web.
131     The semantics of a very high level modeling language such as ASCEND IV
132     are generally much more restrictive than the syntax.
133     For this reason we do not include a BNF description in this paper.
134     ASCEND IV is an experiment.
135     The language is under constant scrutiny and improvement, so this document
136     is under constant revision.
137    
138     \end_layout
139    
140     \begin_layout List
141     \labelwidthstring 00000.00000.00000.000
142     \InsetSpace ~
143    
144     \end_layout
145    
146     \begin_deeper
147 jpye 1384 \begin_layout Chapter
148 johnpye 828 Preliminaries
149     \end_layout
150    
151     \begin_layout Standard
152     We will start off with some background information and some tips that make
153     the rest of the chapter easier to read.
154     ASCEND is an object-oriented (OO) language for hierarchical modeling that
155     has been somewhat specialized for mathematical models.
156     Most of the specialization is in the implementation and the user interface
157     rather than the language definition.
158    
159     \end_layout
160    
161     \begin_layout Standard
162     We feel the single most distinguishing feature of mathematical models is
163     that solving them efficiently requires that the solving algorithms be able
164     to address the entire problem either simultaneously or in a decomposition
165     of the natural problem structure that the algorithm determines is best
166     for the machine(s) in use.
167     In the ASCEND language object-orientation is used to organize natural structure
168     s and make them easier to understand.
169     It is not used to hide the details of the objects.
170     The user (or machine) is free to ignore uninteresting details, and the
171     ASCEND environment provides tools for the runtime suppression of these.
172     \end_layout
173    
174     \begin_layout Standard
175     ASCEND is well into its 4th generation.
176     Some features we will describe are not yet implemented (some merely speculative
177     ) and these are clearly marked (* 4+ *).
178     Any feature not marked (* 4+ *)has been completely implemented, and thus
179     any mismatch between the description given here and the software we distribute
180     is a bug we want you to tell us about.
181    
182     \end_layout
183    
184     \begin_layout Standard
185     The syntax and semantics of ASCEND may seem at first a bit unusual.
186     However, do not be afraid to just try what comes naturally if what we write
187     here is unclear.
188     The parser and compiler of ASCEND IV really will help you get things right.
189     Of course if what we write here is unclear, please ask us about it because
190     we aim to continuously improve both this document and the language system
191     it describes.
192     \end_layout
193    
194     \begin_layout Standard
195     We will describe, starting in Section
196 jpye 1733 \begin_inset LatexCommand vref
197     reference "sub:x.1.2Basic-Elements"
198 johnpye 828
199     \end_inset
200    
201     , the higher level concepts of ASCEND, but first some important punctuation
202     rules.
203     \end_layout
204    
205     \end_deeper
206     \begin_layout List
207     \labelwidthstring 00000.00000.00000.000
208     ASCEND\InsetSpace ~
209     is\InsetSpace ~
210     cAsE\InsetSpace ~
211     sensitive
212 jpye 1733 \begin_inset LatexCommand index
213     name "case sensitive"
214 johnpye 828
215     \end_inset
216    
217     !
218     \end_layout
219    
220     \begin_deeper
221     \begin_layout Standard
222     The keywords that are shown capitalized (or in lower case) in this chapter
223     are that way because ASCEND is case sensitive.
224     IS_A is an ASCEND keyword; isa, Is_a, and all the other permutations you
225     can think of are NOT equivalent to IS_A.
226     In declaring new types of models and variables the user is free to use
227     any style of capitalization he or she may prefer; however, they must remain
228     consistent or undefined types and instances will result.
229     \end_layout
230    
231     \begin_layout Standard
232     This case restriction makes our code very readable, but hard to type without
233     a smart editor.
234     We have kept the case-sensitivity because, like all mathematicians, we
235     find ourselves running out of good variable names if we are restricted
236     to a 26 letter alphabet.
237     We have developed smart add-ins for two UNIX editors, EMACS
238 jpye 1733 \begin_inset LatexCommand index
239     name "EMACS"
240 johnpye 828
241     \end_inset
242    
243     and vi
244 jpye 1733 \begin_inset LatexCommand index
245     name "vi"
246 johnpye 828
247     \end_inset
248    
249     , for handling the upper case keywords and some other syntax elements.
250     The use of these editors is described in another chapter.
251    
252     \end_layout
253    
254     \begin_layout Standard
255     The ASCEND IV parser is very picky and pedantic.
256     It also tries to give helpful messages and occasionally even suggestions.
257     New users should just dive in and make errors, letting the system help
258     them learn how to avoid errors.
259     \end_layout
260    
261 jpye 1384 \begin_layout Section
262 johnpye 828 Punctuation
263 jpye 1733 \begin_inset LatexCommand index
264     name "punctuation"
265 johnpye 828
266     \end_inset
267    
268    
269     \end_layout
270    
271 jpye 1384 \end_deeper
272 johnpye 828 \begin_layout Standard
273     This section covers both the punctuation that must be understood to read
274     this document and the punctuation of ASCEND code.
275     \end_layout
276    
277     \begin_layout List
278     \labelwidthstring 00000.00000.00000.000
279     keywords
280 jpye 1733 \begin_inset LatexCommand index
281     name "keywords"
282 johnpye 828
283     \end_inset
284    
285     : ASCEND keywords and type names are given in the left column in bold format.
286     It is generally clear from the main text which are keywords and which are
287     type names.
288     \end_layout
289    
290     \begin_layout List
291     \labelwidthstring 00000.00000.00000.000
292    
293     \bar under
294     Minor\InsetSpace ~
295     items:
296     \bar default
297     Minor headings that are helpful in finding details are given in the left
298     column in underline format.
299     \end_layout
300    
301     \begin_layout List
302     \labelwidthstring 00000.00000.00000.000
303     Tips: Special notes and hints are sometimes placed on the left.
304     \end_layout
305    
306     \begin_layout List
307     \labelwidthstring 00000.00000.00000.000
308    
309     \bar under
310     LHS
311 jpye 1733 \begin_inset LatexCommand index
312     name "LHS"
313 johnpye 828
314     \end_inset
315    
316     :
317     \bar default
318     Left Hand Side.
319     Abbreviation used frequently.
320     \end_layout
321    
322     \begin_layout List
323     \labelwidthstring 00000.00000.00000.000
324    
325     \bar under
326     RHS
327 jpye 1733 \begin_inset LatexCommand index
328     name "RHS"
329 johnpye 828
330     \end_inset
331    
332     :
333     \bar default
334     Right Hand Side.
335     Abbreviation used frequently.
336     \end_layout
337    
338     \begin_layout List
339     \labelwidthstring 00000.00000.00000.000
340    
341     \bar under
342     Simple\InsetSpace ~
343     names
344 jpye 1733 \begin_inset LatexCommand index
345     name "simple names"
346 johnpye 828
347     \end_inset
348    
349     :
350     \bar default
351     In ASCEND simple names are made of the characters a through z, A through
352     Z, _, (*4+*: $).
353     The underscore is used as a letter, but it cannot be the first letter in
354     a name.
355     The $
356 jpye 1733 \begin_inset LatexCommand index
357     name "\\$"
358 johnpye 828
359     \end_inset
360    
361     character is used exclusively as the first character in the name of system
362     defined built-in parts.
363     "$" is explained in more detail in Section
364 jpye 1733 \begin_inset LatexCommand vref
365     reference "sub:x.6.2Supported-attributes"
366 johnpye 828
367     \end_inset
368    
369     .
370     Simple names should be no more than 80 characters long.
371    
372     \end_layout
373    
374     \begin_layout List
375     \labelwidthstring 00000.00000.00000.000
376    
377     \bar under
378     Compound\InsetSpace ~
379     names
380 jpye 1733 \begin_inset LatexCommand index
381     name "compound names"
382 johnpye 828
383     \end_inset
384    
385     :
386     \bar default
387     Compound names are simple names strung together with dots (.).
388     See the description of "." below.
389     \end_layout
390    
391     \begin_layout List
392     \labelwidthstring 00000.00000.00000.000
393    
394     \bar under
395     Groupings:
396     \end_layout
397    
398     \begin_layout List
399     \labelwidthstring 00000.00000.00000.000
400    
401     \bar under
402 jpye 1733 «\InsetSpace ~
403     »
404 johnpye 828 \bar default
405 jpye 1384 In documentation
406     \series bold
407     optional fields
408     \series default
409    
410 jpye 1733 \begin_inset LatexCommand index
411     name "optional fields"
412 johnpye 828
413     \end_inset
414    
415     are surrounded by these markers.
416     \end_layout
417    
418     \begin_layout List
419     \labelwidthstring 00000.00000.00000.000
420 jpye 1384
421     \family typewriter
422 johnpye 828 (*\InsetSpace ~
423     *)
424 jpye 1384 \family default
425    
426 jpye 1733 \begin_inset LatexCommand index
427     name "(* *)"
428 johnpye 828
429     \end_inset
430    
431     Comment.
432 jpye 1384 Anything inside these is a comment.
433     Comments can nest
434 jpye 1733 \begin_inset LatexCommand index
435     name "nest"
436 johnpye 828
437     \end_inset
438    
439 jpye 1384 in ASCEND and span several lines.
440 johnpye 828 \end_layout
441    
442     \begin_layout List
443     \labelwidthstring 00000.00000.00000.000
444 jpye 1384
445     \family typewriter
446 johnpye 828 (\InsetSpace ~
447     )
448 jpye 1384 \family default
449    
450 jpye 1733 \begin_inset LatexCommand index
451     name "( )"
452 johnpye 828
453     \end_inset
454    
455     Rounded parentheses
456 jpye 1733 \begin_inset LatexCommand index
457     name "parentheses"
458 johnpye 828
459     \end_inset
460    
461    
462 jpye 1733 \begin_inset LatexCommand index
463     name "rounded parentheses"
464 johnpye 828
465     \end_inset
466    
467     .
468     Used to enclose arguments for functions or models where the order of the
469     arguments matters.
470     Also used to group terms in complex arithmetic, logical, or set expressions
471     where the order of operations needs to be specified.
472    
473     \end_layout
474    
475     \begin_layout List
476     \labelwidthstring 00000.00000.00000.000
477     Efficiency\InsetSpace ~
478     tip: The compiler can simplify relation definitions in a particularly
479     efficient manner if constants are grouped together.
480     \end_layout
481    
482     \begin_layout List
483     \labelwidthstring 00000.00000.00000.000
484 jpye 1384
485     \family typewriter
486 johnpye 828 {\InsetSpace ~
487     }
488 jpye 1384 \family default
489    
490 jpye 1733 \begin_inset LatexCommand index
491     name "{ }"
492 johnpye 828
493     \end_inset
494    
495     Curly braces
496 jpye 1733 \begin_inset LatexCommand index
497     name "Curly braces"
498 johnpye 828
499     \end_inset
500    
501     .
502     Used to enclose units.
503     For example, 1 {kg_mole/s}.
504     Also used to enclose the body of annotations.
505     Note: Curly braces are also used in TCL, the language of the ASCEND user
506     interface, about which we will say more in another chapter.
507     \end_layout
508    
509     \begin_layout List
510     \labelwidthstring 00000.00000.00000.000
511 jpye 1384
512     \family typewriter
513 johnpye 828 [\InsetSpace ~
514     ]
515 jpye 1384 \family default
516    
517 jpye 1733 \begin_inset LatexCommand index
518     name "[ ]"
519 johnpye 828
520     \end_inset
521    
522     Square brackets
523 jpye 1733 \begin_inset LatexCommand index
524     name "square brackets"
525 johnpye 828
526     \end_inset
527    
528     .
529     Used to enclose sets or elements of sets.
530     Examples: my_integer_set :== [1,2,3], demonstrates the use of square brackets
531     in the assignment of a set.
532     My_array[1] demonstrates the use of square brackets in naming an array
533     object indexed over an integer set which includes the element 1.
534     \end_layout
535    
536     \begin_layout List
537     \labelwidthstring 00000.00000.00000.000
538 jpye 1384
539     \family typewriter
540 johnpye 828 .
541 jpye 1384 \family default
542    
543 jpye 1733 \begin_inset LatexCommand index
544     name "."
545 johnpye 828
546     \end_inset
547    
548     Dot
549 jpye 1733 \begin_inset LatexCommand index
550     name "dot"
551 johnpye 828
552     \end_inset
553    
554     .
555     The dot is used, as in PASCAL and C, to construct the names of nested objects.
556     Examples: if object a has a part b, then the way to refer to b is as a.b.
557     Tray[1].vle shows a dot following a square bracket; here Tray[1] has a part
558     named vle.
559     \end_layout
560    
561     \begin_layout List
562     \labelwidthstring 00000.00000.00000.000
563 jpye 1384
564     \family typewriter
565 johnpye 828 ..
566 jpye 1384 \family default
567    
568 jpye 1733 \begin_inset LatexCommand index
569     name ".."
570 johnpye 828
571     \end_inset
572    
573     Dot-dot or double dot
574 jpye 1733 \begin_inset LatexCommand index
575     name "double dot"
576 johnpye 828
577     \end_inset
578    
579     .
580     Integer range shorthand.
581     For example, my_integer_set :== [1,2,3] and my_integer_set :== [1..3] are
582     equivalent.
583     If ..
584     appears in a context requiring (), such as the ALIASES/IS_A statement,
585     then the range is expanded and ordered as we would naturally expect.
586     \end_layout
587    
588     \begin_layout List
589     \labelwidthstring 00000.00000.00000.000
590 jpye 1384
591     \family typewriter
592 johnpye 828 :
593 jpye 1384 \family default
594    
595 jpye 1733 \begin_inset LatexCommand index
596     name ":"
597 johnpye 828
598     \end_inset
599    
600     Colon
601 jpye 1733 \begin_inset LatexCommand index
602     name "colon"
603 johnpye 828
604     \end_inset
605    
606     .
607     A separator used in various ways, principally to set the name of an arithmetic
608     relation apart from the definition.
609     \end_layout
610    
611     \begin_layout List
612     \labelwidthstring 00000.00000.00000.000
613 jpye 1384
614     \family typewriter
615 johnpye 828 ::
616 jpye 1384 \family default
617    
618 jpye 1733 \begin_inset LatexCommand index
619     name "::"
620 johnpye 828
621     \end_inset
622    
623     Double colon
624 jpye 1733 \begin_inset LatexCommand index
625     name "double colon"
626 johnpye 828
627     \end_inset
628    
629     .
630     A separator used in the methods section for accessing methods defined on
631     types other than the type the method is part of.
632     Explained in Section
633 jpye 1733 \begin_inset LatexCommand vref
634     reference "sec:x.4Procedural-statements"
635 johnpye 828
636     \end_inset
637    
638     .[
639     \end_layout
640    
641     \begin_layout List
642     \labelwidthstring 00000.00000.00000.000
643 jpye 1384
644     \family typewriter
645 johnpye 828 ;
646 jpye 1384 \family default
647    
648 jpye 1733 \begin_inset LatexCommand index
649     name ";"
650 johnpye 828
651     \end_inset
652    
653     Semicolon
654 jpye 1733 \begin_inset LatexCommand index
655     name "semicolon"
656 johnpye 828
657     \end_inset
658    
659     .
660     The separator of statements.
661     \end_layout
662    
663     \begin_deeper
664 jpye 1384 \begin_layout Section
665 johnpye 828 Basic Elements
666 jpye 1733 \begin_inset LatexCommand index
667     name "basic elements"
668 johnpye 828
669     \end_inset
670    
671    
672 jpye 1733 \begin_inset LatexCommand label
673     name "sub:x.1.2Basic-Elements"
674 johnpye 828
675     \end_inset
676    
677    
678     \end_layout
679    
680     \end_deeper
681     \begin_layout List
682     \labelwidthstring 00000.00000.00000.000
683    
684     \bar under
685     Boolean\InsetSpace ~
686     value
687     \bar default
688    
689 jpye 1733 \begin_inset LatexCommand index
690     name "value, Boolean"
691 johnpye 828
692     \end_inset
693    
694    
695 jpye 1733 \begin_inset LatexCommand index
696     name "Boolean value"
697 johnpye 828
698     \end_inset
699    
700 jpye 1384
701     \family sans
702     TRUE
703     \family default
704    
705 jpye 1733 \begin_inset LatexCommand index
706     name "TRUE"
707 johnpye 828
708     \end_inset
709    
710 jpye 1384 or
711     \family sans
712     FALSE
713     \family default
714    
715 jpye 1733 \begin_inset LatexCommand index
716     name "FALSE"
717 johnpye 828
718     \end_inset
719    
720     .
721 jpye 1384 Can't get much simpler, eh? In the language definition
722     \family sans
723     TRUE
724     \family default
725     and
726     \family sans
727     FALSE
728     \family default
729     do not map to 1 and 0 or any other type of numeric value.
730 johnpye 828 (In the implementation, of course, they do.)
731     \end_layout
732    
733     \begin_layout List
734     \labelwidthstring 00000.00000.00000.000
735     User\InsetSpace ~
736     interface\InsetSpace ~
737     tip: The ASCEND user interface programmers have found it very
738     convenient, however, to allow T/F, 1/0, Y/N, and other obvious boolean
739     conventions as interactive input when assigning boolean values.
740     We are lazy users.
741     \end_layout
742    
743     \begin_layout List
744     \labelwidthstring 00000.00000.00000.000
745    
746     \bar under
747     Integer\InsetSpace ~
748     value
749     \bar default
750    
751 jpye 1733 \begin_inset LatexCommand index
752     name "value, integer"
753 johnpye 828
754     \end_inset
755    
756    
757 jpye 1733 \begin_inset LatexCommand index
758     name "integer value"
759 johnpye 828
760     \end_inset
761    
762     A signed whole number up to the maximum that can be represented by the
763     computer on which one is running ASCEND.
764 jpye 1384
765     \family sans
766     MAX_INTEGER
767     \family default
768    
769 jpye 1733 \begin_inset LatexCommand index
770     name "MAX\\_INTEGER"
771 johnpye 828
772     \end_inset
773    
774     is machine dependent.
775     Examples are:
776     \end_layout
777    
778     \begin_deeper
779     \begin_layout LyX-Code
780     \align block
781     123
782     \end_layout
783    
784     \begin_layout LyX-Code
785     \align block
786     -5
787     \end_layout
788    
789     \begin_layout LyX-Code
790     \align block
791     MAX_INTEGER, typically 2147483647.
792     \end_layout
793    
794     \end_deeper
795     \begin_layout List
796     \labelwidthstring 00000.00000.00000.000
797    
798     \bar under
799     Real\InsetSpace ~
800     value
801     \bar default
802    
803 jpye 1733 \begin_inset LatexCommand index
804     name "value. real"
805 johnpye 828
806     \end_inset
807    
808    
809 jpye 1733 \begin_inset LatexCommand index
810     name "real value"
811 johnpye 828
812     \end_inset
813    
814     ASCEND represents reals almost exactly as any other mathematically oriented
815     programming language does.
816     The mantissa
817 jpye 1733 \begin_inset LatexCommand index
818     name "mantissa"
819 johnpye 828
820     \end_inset
821    
822     has an optional negative sign followed by a string of digits and at most
823     one decimal point.
824 jpye 1384 The exponent is the letter
825     \family typewriter
826     e
827     \family default
828     or
829     \family typewriter
830     E
831     \family default
832     followed by an integer.
833 johnpye 828 The number must not exceed the largest the computer is able to handle.
834     There can be no blank characters in a real.
835 jpye 1384
836     \family sans
837     MAX_REAL
838     \family default
839    
840 jpye 1733 \begin_inset LatexCommand index
841     name "MAX\\_REAL"
842 johnpye 828
843     \end_inset
844    
845     is machine dependent.
846     The following are legitimate reals in ASCEND:
847     \end_layout
848    
849     \begin_deeper
850     \begin_layout LyX-Code
851     \align block
852     -1
853     \end_layout
854    
855     \begin_layout LyX-Code
856     \align block
857     1.2
858     \end_layout
859    
860     \begin_layout LyX-Code
861     \align block
862     1.3e-2
863     \end_layout
864    
865     \begin_layout LyX-Code
866     \align block
867     7.888888e+34
868     \end_layout
869    
870     \begin_layout LyX-Code
871     \align block
872     .6E21
873     \end_layout
874    
875     \begin_layout LyX-Code
876     \align block
877     MAX_REAL, typically about 1.79E+308.
878     \end_layout
879    
880     \begin_layout Standard
881     while the following are not:
882     \end_layout
883    
884     \begin_layout LyX-Code
885     \align block
886     1.
887 jpye 1384 2 (*contains a blank within it*)
888 johnpye 828 \end_layout
889    
890     \begin_layout LyX-Code
891     \align block
892     1.3e2.0 (*exponent has a decimal in it*)
893     \end_layout
894    
895 jpye 1384 \begin_layout LyX-Code
896    
897     \family typewriter
898     +1.3 (* illegal unary + sign.
899 johnpye 828 x = +1.3 not allowed*)
900     \end_layout
901    
902     \end_deeper
903     \begin_layout List
904     \labelwidthstring 00000.00000.00000.000
905    
906     \bar under
907     Reals\InsetSpace ~
908     stored\InsetSpace ~
909     in\InsetSpace ~
910     SI
911 jpye 1733 \begin_inset LatexCommand index
912     name "SI"
913 johnpye 828
914     \end_inset
915    
916     \InsetSpace ~
917     units
918     \bar default
919    
920     \end_layout
921    
922     \begin_deeper
923     \begin_layout Standard
924     We store all real values as double precision
925 jpye 1733 \begin_inset LatexCommand index
926     name "double precision"
927 johnpye 828
928     \end_inset
929    
930 jpye 1384 numbers in the metre-kilogram-second (MKS)
931 jpye 1733 \begin_inset LatexCommand index
932     name "MKS"
933 johnpye 828
934     \end_inset
935    
936     system of units.
937     This eliminates many common errors in the modeling of physical systems.
938     Since we also place the burden of scaling equations on system routines
939     and a simple modeling methodology, the internal units are not of concern
940     to most users.
941     \end_layout
942    
943     \end_deeper
944     \begin_layout List
945     \labelwidthstring 00000.00000.00000.000
946    
947     \bar under
948     Dimensionality
949 jpye 1733 \begin_inset LatexCommand index
950     name "dimensionality"
951 johnpye 828
952     \end_inset
953    
954     :
955     \bar default
956     Real values have dimensionality such as length/time for velocity.
957 jpye 1384
958     \series bold
959     Dimensionality
960     \series default
961     is to be distinguished from the
962     \series bold
963     units
964     \series default
965     such as ft/s.
966 johnpye 828 ASCEND takes care of mapping between units
967 jpye 1733 \begin_inset LatexCommand index
968     name "units"
969 johnpye 828
970     \end_inset
971    
972     and dimensions.
973     A value without units (this includes integer values) is taken to be dimensionle
974     ss
975 jpye 1733 \begin_inset LatexCommand index
976     name "dimensionless"
977 johnpye 828
978     \end_inset
979    
980     .
981     Dimensionality is built up from the following base dimensions:
982     \end_layout
983    
984     \begin_layout List
985     \labelwidthstring 00000.00000.00000.000
986     Name
987     \bar under
988     definition; typical units
989     \end_layout
990    
991     \begin_layout List
992     \labelwidthstring 00000.00000.00000.000
993     L
994 jpye 1733 \begin_inset LatexCommand index
995     name "L, length dimension"
996 johnpye 828
997     \end_inset
998    
999     length
1000 jpye 1733 \begin_inset LatexCommand index
1001     name "length"
1002 johnpye 828
1003     \end_inset
1004    
1005 jpye 1384 ; metre, m
1006 johnpye 828 \end_layout
1007    
1008     \begin_layout List
1009     \labelwidthstring 00000.00000.00000.000
1010     M
1011 jpye 1733 \begin_inset LatexCommand index
1012     name "M, mass dimension"
1013 johnpye 828
1014     \end_inset
1015    
1016     mass
1017 jpye 1733 \begin_inset LatexCommand index
1018     name "mass"
1019 johnpye 828
1020     \end_inset
1021    
1022     ; kilogram, kg
1023     \end_layout
1024    
1025     \begin_layout List
1026     \labelwidthstring 00000.00000.00000.000
1027     T
1028 jpye 1733 \begin_inset LatexCommand index
1029     name "T, time dimension"
1030 johnpye 828
1031     \end_inset
1032    
1033     time
1034 jpye 1733 \begin_inset LatexCommand index
1035     name "time"
1036 johnpye 828
1037     \end_inset
1038    
1039     ; second, s
1040     \end_layout
1041    
1042     \begin_layout List
1043     \labelwidthstring 00000.00000.00000.000
1044     E
1045 jpye 1733 \begin_inset LatexCommand index
1046     name "E, electric current dimension"
1047 johnpye 828
1048     \end_inset
1049    
1050     electric current
1051 jpye 1733 \begin_inset LatexCommand index
1052     name "electric current"
1053 johnpye 828
1054     \end_inset
1055    
1056     ; ampere, A
1057     \end_layout
1058    
1059     \begin_layout List
1060     \labelwidthstring 00000.00000.00000.000
1061     Q
1062 jpye 1733 \begin_inset LatexCommand index
1063     name "Q, quantity dimension"
1064 johnpye 828
1065     \end_inset
1066    
1067     quantity
1068 jpye 1733 \begin_inset LatexCommand index
1069     name "quantity"
1070 johnpye 828
1071     \end_inset
1072    
1073     ; mole, mole
1074     \end_layout
1075    
1076     \begin_layout List
1077     \labelwidthstring 00000.00000.00000.000
1078     TMP
1079 jpye 1733 \begin_inset LatexCommand index
1080     name "TMP, temperature dimension"
1081 johnpye 828
1082     \end_inset
1083    
1084     temperature
1085 jpye 1733 \begin_inset LatexCommand index
1086     name "temperature"
1087 johnpye 828
1088     \end_inset
1089    
1090     ; Kelvin, K
1091     \end_layout
1092    
1093     \begin_layout List
1094     \labelwidthstring 00000.00000.00000.000
1095     LUM
1096 jpye 1733 \begin_inset LatexCommand index
1097     name "LUM, luminous intensity dimension"
1098 johnpye 828
1099     \end_inset
1100    
1101     luminous intensity
1102 jpye 1733 \begin_inset LatexCommand index
1103     name "luminous intensity"
1104 johnpye 828
1105     \end_inset
1106    
1107     ; candela, cd
1108     \end_layout
1109    
1110     \begin_layout List
1111     \labelwidthstring 00000.00000.00000.000
1112     P
1113 jpye 1733 \begin_inset LatexCommand index
1114     name "P, phase angle dimension"
1115 johnpye 828
1116     \end_inset
1117    
1118     plane angle
1119 jpye 1733 \begin_inset LatexCommand index
1120     name "plane angle"
1121 johnpye 828
1122     \end_inset
1123    
1124     ; radian, rad
1125     \end_layout
1126    
1127     \begin_layout List
1128     \labelwidthstring 00000.00000.00000.000
1129     S
1130 jpye 1733 \begin_inset LatexCommand index
1131     name "S, solid angle dimension"
1132 johnpye 828
1133     \end_inset
1134    
1135     solid angle
1136 jpye 1733 \begin_inset LatexCommand index
1137     name "solid angle"
1138 johnpye 828
1139     \end_inset
1140    
1141     ; steradian, srad
1142     \end_layout
1143    
1144     \begin_layout List
1145     \labelwidthstring 00000.00000.00000.000
1146     C
1147 jpye 1733 \begin_inset LatexCommand index
1148     name "C, currency dimension"
1149 johnpye 828
1150     \end_inset
1151    
1152     currency
1153 jpye 1733 \begin_inset LatexCommand index
1154     name "currency"
1155 johnpye 828
1156     \end_inset
1157    
1158     ; currency, CR
1159     \end_layout
1160    
1161     \begin_deeper
1162     \begin_layout Standard
1163     The atom and constant definitions in the library illustrate the use of dimension
1164     ality.
1165     \end_layout
1166    
1167     \begin_layout Standard
1168     Dimensions may be any combination of these symbols along with rounded parenthese
1169 jpye 1384 s, (), and the operators *,
1170     \family typewriter
1171     ^
1172     \family default
1173     and
1174     \family typewriter
1175     /
1176     \family default
1177     .
1178     Examples include
1179     \family typewriter
1180     M/T
1181     \family default
1182     or
1183     \family typewriter
1184     M*L^2/T^2/TMP
1185     \family default
1186     {this latter means
1187     \family typewriter
1188     (M*(L^2)/(T^2))/TMP
1189     \family default
1190     }.
1191     The second operand for the to-the-power-of operator,
1192     \family typewriter
1193     ^
1194     \family default
1195     , must be an integer value (e.g., -2 or 3) because fractional powers of dimensiona
1196     l numbers are physically undefined
1197     \begin_inset Note Note
1198     status open
1199    
1200     \begin_layout Standard
1201     although we do seem them occasionally...
1202 johnpye 828 \end_layout
1203    
1204 jpye 1384 \end_inset
1205    
1206     .
1207     \end_layout
1208    
1209 johnpye 828 \begin_layout Standard
1210     If the dimensionality for a real value is undefined, then ASCEND gives it
1211 jpye 1384 a wildcard dimensionality
1212 jpye 1733 \begin_inset LatexCommand index
1213     name "wild card dimensionality"
1214 johnpye 828
1215     \end_inset
1216    
1217     .
1218     If ASCEND can later deduce its dimensionality from its use in a model definitio
1219     n it will do so.
1220 jpye 1384 For example consider the real variable
1221     \family typewriter
1222     a
1223     \family default
1224     , suppose
1225     \family typewriter
1226     a
1227     \family default
1228     has wildcard dimensionality,
1229     \family typewriter
1230     b
1231     \family default
1232     has dimensionality of
1233     \family typewriter
1234     L/T
1235     \family default
1236     .
1237 johnpye 828 Then the statement:
1238     \end_layout
1239    
1240     \end_deeper
1241     \begin_layout List
1242     \labelwidthstring 00000.00000.00000.000
1243     Example\InsetSpace ~
1244     of\InsetSpace ~
1245     a\InsetSpace ~
1246     dimensionally\InsetSpace ~
1247     consistent
1248 jpye 1733 \begin_inset LatexCommand index
1249     name "dimensionally consistent"
1250 johnpye 828
1251     \end_inset
1252    
1253     \InsetSpace ~
1254     equation.
1255    
1256     \end_layout
1257    
1258     \begin_layout List
1259     \labelwidthstring 00000.00000.00000.000
1260     \InsetSpace ~
1261 jpye 1384
1262     \family typewriter
1263     a + b = 3 {ft/s};
1264 johnpye 828 \end_layout
1265    
1266     \begin_deeper
1267     \begin_layout Standard
1268 jpye 1384 requires that
1269     \family typewriter
1270     a
1271     \family default
1272     have the same dimensionality as the other two terms, namely,
1273     \family typewriter
1274     L/T
1275     \family default
1276     .
1277     ASCEND will assign this dimensionality to
1278     \family typewriter
1279     a
1280     \family default
1281     .
1282 johnpye 828 The user will be warned of dimensionally inconsistent equations.
1283     \end_layout
1284    
1285     \end_deeper
1286     \begin_layout List
1287     \labelwidthstring 00000.00000.00000.000
1288    
1289     \bar under
1290     Unit\InsetSpace ~
1291     expression
1292     \bar default
1293     A unit expression
1294 jpye 1733 \begin_inset LatexCommand index
1295     name "unit expression"
1296 johnpye 828
1297     \end_inset
1298    
1299     may be composed of any combination of unit names defined by the system
1300 jpye 1384 and any numerical constants combined with times (
1301     \family typewriter
1302     *
1303     \family default
1304     ), divide(
1305     \family typewriter
1306     /
1307     \family default
1308     ) and to the power (
1309     \family typewriter
1310     ^
1311     \family default
1312     ) operators.
1313     The RHS of
1314     \family typewriter
1315     ^
1316     \family default
1317     must be an integer.
1318     Parentheses can be used to group subexpressions with the exception that
1319     a divide operator may
1320     \emph on
1321     not
1322     \emph default
1323     be followed by a grouped subexpression.
1324 johnpye 828
1325     \end_layout
1326    
1327     \begin_deeper
1328     \begin_layout Standard
1329 jpye 1384 So,
1330     \family typewriter
1331     {kg/m/s}
1332     \family default
1333     is fine, but
1334     \family typewriter
1335     {kg/(m*s)}
1336     \family default
1337     is not.
1338 johnpye 828 Although the two expressions are mathematically equivalent, it makes the
1339     system programming and output formatting easier to code and faster to execute
1340     if we disallow expressions of the latter sort.
1341     \end_layout
1342    
1343     \begin_layout Standard
1344 jpye 1384 The units understood by the system are defined in the first part of this
1345     manual.
1346 johnpye 828 Note that several units defined are really values of interesting constants
1347     in SI, e.g.
1348 jpye 1384
1349     \family typewriter
1350     R :== 1{GAS_C}
1351     \family default
1352     yields the correct value of the thermodynamic gas constant.
1353 johnpye 828 Users can define additional units.
1354     \end_layout
1355    
1356     \end_deeper
1357     \begin_layout List
1358     \labelwidthstring 00000.00000.00000.000
1359    
1360     \bar under
1361     Units
1362     \bar default
1363    
1364 jpye 1733 \begin_inset LatexCommand index
1365     name "units"
1366 johnpye 828
1367     \end_inset
1368    
1369 jpye 1384 A Unit expression unit expression must be enclosed in curly braces
1370     \family typewriter
1371     {}
1372     \family default
1373     .
1374 johnpye 828 When a real number is used in a mathematical expression in ASCEND, it must
1375     have a set of units expressed with it.
1376     If it does not, ASCEND assumes the number is dimensionless, which may not
1377     be the intent of the modeler.
1378     An example is shown in the dimensionally consistent equation above where
1379 jpye 1384 the number 3 has the units
1380     \family typewriter
1381     {ft/s}
1382     \family default
1383     associated with it.
1384 johnpye 828
1385     \end_layout
1386    
1387     \begin_deeper
1388     \begin_layout Standard
1389     Examples:
1390     \end_layout
1391    
1392     \begin_layout LyX-Code
1393     \align block
1394     {kg_mole/s/m} same as {(kg_mole/s)/m}
1395     \end_layout
1396    
1397     \begin_layout LyX-Code
1398     \align block
1399     {m^3/yr}
1400     \end_layout
1401    
1402     \begin_layout LyX-Code
1403     \align block
1404     {3/100*ft} same as {0.03*ft}
1405     \end_layout
1406    
1407     \begin_layout LyX-Code
1408     \align block
1409     {s^-1} same as {1/s}
1410     \end_layout
1411    
1412     \begin_layout Standard
1413     Illegal unit examples are
1414     \end_layout
1415    
1416     \begin_layout LyX-Code
1417     \align block
1418     {m/(K*kg_mole)}
1419     \end_layout
1420    
1421     \begin_deeper
1422     \begin_layout Standard
1423     grouped subexpression used in the denominator; should be written {m/K/kg_mole}.
1424     \end_layout
1425    
1426     \end_deeper
1427     \begin_layout LyX-Code
1428     \align block
1429     {m^3.5}
1430     \end_layout
1431    
1432     \begin_deeper
1433     \begin_layout Standard
1434     power of units or dimensions must be integer.
1435     \end_layout
1436    
1437     \end_deeper
1438     \end_deeper
1439     \begin_layout List
1440     \labelwidthstring 00000.00000.00000.000
1441    
1442     \bar under
1443     Symbol\InsetSpace ~
1444     Value
1445     \bar default
1446    
1447 jpye 1733 \begin_inset LatexCommand index
1448     name "value, symbol"
1449 johnpye 828
1450     \end_inset
1451    
1452    
1453 jpye 1733 \begin_inset LatexCommand index
1454     name "symbol value"
1455 johnpye 828
1456     \end_inset
1457    
1458     The format for a symbol is that of an arbitrary character string enclosed
1459     between two single quotes.
1460     There is no way to embed a single quote
1461 jpye 1733 \begin_inset LatexCommand index
1462     name "'"
1463 johnpye 828
1464     \end_inset
1465    
1466    
1467 jpye 1733 \begin_inset LatexCommand index
1468     name "single quote"
1469 johnpye 828
1470     \end_inset
1471    
1472     in a symbol: we are not in the escape sequence business at this time.
1473     The following are legal symbols in ASCEND:
1474     \end_layout
1475    
1476     \begin_deeper
1477     \begin_layout LyX-Code
1478     'H2O'
1479     \end_layout
1480    
1481     \begin_layout LyX-Code
1482     'r1'
1483     \end_layout
1484    
1485     \begin_layout LyX-Code
1486     'Bill said,foo to whom?'
1487     \end_layout
1488    
1489     \begin_layout Standard
1490     while the following are not legal symbol values:
1491     \end_layout
1492    
1493     \begin_layout LyX-Code
1494     "ethanol" (double quotes not allowed)
1495     \end_layout
1496    
1497     \begin_layout LyX-Code
1498     water (no single quotes given)
1499     \end_layout
1500    
1501     \begin_layout LyX-Code
1502 jpye 1733 'i can't do this' (no embedded quotes)
1503 johnpye 828 \end_layout
1504    
1505     \begin_layout Standard
1506     There is an arbitrary upper limit to the number of characters in a symbol
1507     (something like 10,000) so that we may detect a missing close quote in
1508     a bad input file without crashing.
1509     \end_layout
1510    
1511     \end_deeper
1512     \begin_layout List
1513     \labelwidthstring 00000.00000.00000.000
1514     Sets\InsetSpace ~
1515     values
1516 jpye 1733 \begin_inset LatexCommand index
1517     name "values, set"
1518 johnpye 828
1519     \end_inset
1520    
1521    
1522 jpye 1733 \begin_inset LatexCommand index
1523     name "set values"
1524 johnpye 828
1525     \end_inset
1526    
1527 jpye 1384 Set values are lists of elements, all of type
1528     \family sans
1529     integer_constant
1530     \family default
1531     or all of type
1532     \family sans
1533     symbol_constant
1534     \family default
1535     , enclosed between square brackets
1536     \family typewriter
1537     []
1538     \family default
1539     .
1540 johnpye 828 The following are examples of sets:
1541     \end_layout
1542    
1543     \begin_deeper
1544     \begin_layout LyX-Code
1545     \align block
1546     ['methane', 'ethane', 'propane']
1547     \end_layout
1548    
1549     \begin_layout LyX-Code
1550     \align block
1551     [1..5, 7, 15]
1552     \end_layout
1553    
1554     \begin_layout LyX-Code
1555     \align block
1556     [2..n_stages]
1557     \end_layout
1558    
1559     \begin_layout LyX-Code
1560     \align block
1561     [1, 4, 2, 1, 16]
1562     \end_layout
1563    
1564     \begin_layout LyX-Code
1565     \align block
1566     []
1567     \end_layout
1568    
1569     \end_deeper
1570     \begin_layout List
1571     \labelwidthstring 00000.00000.00000.000
1572     More\InsetSpace ~
1573     about\InsetSpace ~
1574     sets
1575 jpye 1733 \begin_inset LatexCommand index
1576     name "sets"
1577 johnpye 828
1578     \end_inset
1579    
1580     \InsetSpace ~
1581     in\InsetSpace ~
1582     Section\InsetSpace ~
1583    
1584 jpye 1733 \begin_inset LatexCommand vref
1585     reference "sub:x.2.2Sets"
1586 johnpye 828
1587     \end_inset
1588    
1589     .
1590     \end_layout
1591    
1592     \begin_deeper
1593     \begin_layout Standard
1594 jpye 1384 The value range
1595     \family typewriter
1596     1..5
1597     \family default
1598     is an allowable shorthand for the integers 1, 2, 3, 4 and 5 while the value
1599     range
1600     \family typewriter
1601     2..n_stages
1602     \family default
1603     (where
1604     \family typewriter
1605     n_stages
1606     \family default
1607     must be of type
1608     \family sans
1609     integer_constant
1610     \family default
1611     ) means all integers from 2 to
1612     \family typewriter
1613     n_stages
1614     \family default
1615     .
1616     If
1617     \family typewriter
1618     n_stages
1619     \family default
1620     is less than 2, then the third set is empty.
1621     The repeated occurrence of
1622     \family typewriter
1623     1
1624     \family default
1625     in the fourth set is ignored.
1626 johnpye 828 The fifth set is the empty set
1627 jpye 1733 \begin_inset LatexCommand index
1628     name "empty set"
1629 johnpye 828
1630     \end_inset
1631    
1632    
1633 jpye 1733 \begin_inset LatexCommand index
1634     name "set, empty"
1635 johnpye 828
1636     \end_inset
1637    
1638     .
1639     \end_layout
1640    
1641     \begin_layout Standard
1642     We use the term set in an almost pure mathematical sense.
1643     The elements have no order.
1644     One can only ask two things of a set: (1) if an element is a member of
1645     it and (2) its cardinality
1646 jpye 1733 \begin_inset LatexCommand index
1647     name "cardinality"
1648 johnpye 828
1649     \end_inset
1650    
1651 jpye 1384 (
1652     \family sans
1653     CARD
1654     \family default
1655    
1656 jpye 1733 \begin_inset LatexCommand index
1657     name "CARD"
1658 johnpye 828
1659     \end_inset
1660    
1661 jpye 1384
1662     \family typewriter
1663     (set)
1664     \family default
1665     ).
1666 johnpye 828 Repeated elements used in defining a set are ignored.
1667     The elements of sets cannot themselves be sets in ASCEND; i.e., there can
1668     be no sets of set.
1669     \end_layout
1670    
1671     \end_deeper
1672     \begin_layout List
1673     \labelwidthstring 00000.00000.00000.000
1674     Sets\InsetSpace ~
1675     are\InsetSpace ~
1676     unordered.
1677     A set of integers may appear to be ordered to the modeler as the natural
1678     numbers have an order.
1679     However, it is the user imposing and using the ordering, not ASCEND.
1680     ASCEND sees these integers as elements in the set with NO ordering.
1681     Therefore, there are no operators in ASCEND such as successor or precursor
1682     member of a set.
1683     \end_layout
1684    
1685     \begin_layout List
1686     \labelwidthstring 00000.00000.00000.000
1687    
1688     \bar under
1689     Arrays
1690     \bar default
1691    
1692 jpye 1733 \begin_inset LatexCommand index
1693     name "arrays"
1694 johnpye 828
1695     \end_inset
1696    
1697     An array is a list of instances indexed over a set, in computer-speak,
1698     an associative array of objects.
1699     The instances are all of the same base type (as that is the only way they
1700     can be defined).
1701     An individual member of a list may later be more refined than the other
1702     members (we shall illustrate that possibility).
1703     The following are arrays in ASCEND.
1704     \end_layout
1705    
1706     \begin_deeper
1707     \begin_layout LyX-Code
1708     \align block
1709     stage[1..n_stages]
1710     \end_layout
1711    
1712     \begin_layout LyX-Code
1713     \align block
1714     y[components]
1715     \end_layout
1716    
1717     \begin_layout LyX-Code
1718     \align block
1719     column[areas][processes]
1720     \end_layout
1721    
1722     \begin_layout Standard
1723     where components, areas and processes are sets.
1724 jpye 1384 For example components could be the set of symbols
1725     \family typewriter
1726     ['ethylene', 'propylene']
1727     \family default
1728     , areas the set of symbols
1729     \family typewriter
1730     ['feed_prep', 'prod_purification']
1731     \family default
1732     while processes could be the set
1733     \family typewriter
1734     ['alcohol_manuf', 'poly_propropylene_manuf']
1735     \family default
1736     .
1737     Note that the third example (
1738     \family typewriter
1739     column
1740     \family default
1741     ) is a list of lists (the way that ASCEND permits a multiply subscripted
1742     array).
1743 johnpye 828
1744     \end_layout
1745    
1746     \begin_layout Standard
1747     The following are elements in the above arrays:
1748     \end_layout
1749    
1750     \begin_layout LyX-Code
1751     stage[1]
1752     \end_layout
1753    
1754     \begin_layout LyX-Code
1755     y['ethylene']
1756     \end_layout
1757    
1758     \begin_layout LyX-Code
1759     column['feed_prep'][alcohol_manuf']
1760     \end_layout
1761    
1762     \begin_layout Standard
1763 jpye 1384 provided that
1764     \family typewriter
1765     n_stages
1766     \family default
1767     is 1 or larger.
1768 johnpye 828
1769     \end_layout
1770    
1771     \begin_layout Standard
1772     There can be any number of subscripts
1773 jpye 1733 \begin_inset LatexCommand index
1774     name "subscripts"
1775 johnpye 828
1776     \end_inset
1777    
1778     for an array.
1779     We point out, however, that in virtually every application of arrays requiring
1780     more than two subscripts, there is usually a some underlying concept that
1781     is much better modeled as an object than as part of a deeply subscripted
1782 jpye 1733 \begin_inset LatexCommand index
1783     name "subscripted, deeply"
1784 johnpye 828
1785     \end_inset
1786    
1787    
1788 jpye 1733 \begin_inset LatexCommand index
1789     name "deeply subscripted"
1790 johnpye 828
1791     \end_inset
1792    
1793     array.
1794     In the following jagged array example, there are really the concepts of
1795     unit operation and stream that would be better understood if made explicit.
1796     \end_layout
1797    
1798     \end_deeper
1799     \begin_layout List
1800     \labelwidthstring 00000.00000.00000.000
1801    
1802     \bar under
1803     Arrays\InsetSpace ~
1804     can\InsetSpace ~
1805     be\InsetSpace ~
1806     jagged
1807     \bar default
1808    
1809 jpye 1733 \begin_inset LatexCommand label
1810     name "lyx:Arrays-can-be"
1811 johnpye 828
1812     \end_inset
1813    
1814 jpye 1384 Arrays can be sparse
1815 jpye 1733 \begin_inset LatexCommand index
1816     name "sparse"
1817 johnpye 828
1818     \end_inset
1819    
1820     or jagged
1821 jpye 1733 \begin_inset LatexCommand index
1822     name "jagged"
1823 johnpye 828
1824     \end_inset
1825    
1826     .
1827     For example:
1828     \end_layout
1829    
1830     \begin_deeper
1831     \begin_layout LyX-Code
1832     process[1..3] IS_A set OF integer;
1833     \end_layout
1834    
1835     \begin_layout LyX-Code
1836     process[1] :== [2];
1837     \end_layout
1838    
1839     \begin_layout LyX-Code
1840     process[2] :== [7,5,3];
1841     \end_layout
1842    
1843     \begin_layout LyX-Code
1844     process[3] :== [4,6];
1845     \end_layout
1846    
1847     \begin_layout LyX-Code
1848     FOR i in [1..3] CREATE
1849     \end_layout
1850    
1851     \begin_layout LyX-Code
1852     FOR j IN process[i] CREATE
1853     \end_layout
1854    
1855     \begin_layout LyX-Code
1856     flow[i][j] IS_A mass;
1857     \end_layout
1858    
1859     \begin_layout LyX-Code
1860     END FOR;
1861     \end_layout
1862    
1863     \begin_layout LyX-Code
1864     END FOR;
1865     \end_layout
1866    
1867     \begin_layout Standard
1868     process is an array of sets (not to be confused with a set of sets which
1869     ASCEND does not have) and flow is an array with six elements spread over
1870     three rows:
1871     \end_layout
1872    
1873     \begin_layout LyX-Code
1874     flow[1][2]
1875     \end_layout
1876    
1877     \begin_layout LyX-Code
1878     flow[2][7], flow[2][3], flow[2][5]
1879     \end_layout
1880    
1881     \begin_layout LyX-Code
1882     flow[3][4], flow[3][6]
1883     \end_layout
1884    
1885     \end_deeper
1886     \begin_layout List
1887     \labelwidthstring 00000.00000.00000.000
1888     Arrays\InsetSpace ~
1889     are\InsetSpace ~
1890     also\InsetSpace ~
1891     instances
1892     \end_layout
1893    
1894     \begin_deeper
1895     \begin_layout Standard
1896     Each array is itself an object.
1897 jpye 1384 That is, when you write
1898     \family typewriter
1899     a[1..2] IS_A real
1900     \family default
1901     , three objects get created:
1902     \family typewriter
1903     a[1]
1904     \family default
1905     ,
1906     \family typewriter
1907     a[2]
1908     \family default
1909     , and
1910     \family typewriter
1911     a
1912     \family default
1913     .
1914     The object
1915     \family typewriter
1916     a
1917     \family default
1918     is an array instance which has parts named
1919     \family typewriter
1920     [1]
1921     \family default
1922     and
1923     \family typewriter
1924     [2]
1925     \family default
1926     that are real instances.
1927 johnpye 828 When a parameterized model requires an array, you pass it the single item
1928 jpye 1384
1929     \family typewriter
1930     a
1931     \family default
1932     , not the elements
1933     \family typewriter
1934     a[1..2]
1935     \family default
1936     .
1937 johnpye 828 \end_layout
1938    
1939     \end_deeper
1940     \begin_layout List
1941     \labelwidthstring 00000.00000.00000.000
1942     No\InsetSpace ~
1943     contiguous\InsetSpace ~
1944     storage
1945 jpye 1733 \begin_inset LatexCommand index
1946     name "contiguous storage, no"
1947 johnpye 828
1948     \end_inset
1949    
1950    
1951     \end_layout
1952    
1953     \begin_deeper
1954     \begin_layout Standard
1955     Just in case you still have not caught on, ASCEND arrays are not blocks
1956     of memory such as are seen in low-level languages like C
1957 jpye 1733 \begin_inset LatexCommand index
1958     name "C, computer language"
1959 johnpye 828
1960     \end_inset
1961    
1962     , FORTRAN
1963 jpye 1733 \begin_inset LatexCommand index
1964     name "FORTRAN"
1965 johnpye 828
1966     \end_inset
1967    
1968     , and Matlab
1969 jpye 1733 \begin_inset LatexCommand index
1970     name "Matlab"
1971 johnpye 828
1972     \end_inset
1973    
1974     .
1975     The modeling language does not provide things like MatMult
1976 jpye 1733 \begin_inset LatexCommand index
1977     name "MatMult"
1978 johnpye 828
1979     \end_inset
1980    
1981     , Transpose
1982 jpye 1733 \begin_inset LatexCommand index
1983     name "Transpose"
1984 johnpye 828
1985     \end_inset
1986    
1987     , and Inverse
1988 jpye 1733 \begin_inset LatexCommand index
1989     name "Inverse"
1990 johnpye 828
1991     \end_inset
1992    
1993     because these are procedural solving tools.
1994     If you are dedicated, you could write METHODs that implement matrix algebra,
1995     but this is a really dumb idea.
1996     We aim to structure our software so that it can interact openly with separate,
1997     dedicated tools (such as Matlab) when those tools are needed.
1998     \end_layout
1999    
2000     \end_deeper
2001     \begin_layout List
2002     \labelwidthstring 00000.00000.00000.000
2003     Index\InsetSpace ~
2004     variable
2005 jpye 1733 \begin_inset LatexCommand index
2006     name "index variable"
2007 johnpye 828
2008     \end_inset
2009    
2010     One can introduce a variable as an index ranging over a set.
2011     Index variables are local to the statements in which they occur.
2012     An example of using an index variable is the following FOR statement:
2013     \end_layout
2014    
2015     \begin_deeper
2016     \begin_layout LyX-Code
2017     FOR i IN components CREATE
2018     \end_layout
2019    
2020     \begin_layout LyX-Code
2021     VLE_equil[i]: y[i] = K[i]*x[i];
2022     \end_layout
2023    
2024     \begin_layout LyX-Code
2025     END FOR;
2026     \end_layout
2027    
2028     \begin_layout Standard
2029     In this example i implicitly is of the same type as the values in the set
2030     components.
2031     If another object i exists in the model containing the FOR loop, it is
2032     ignored while executing the statements in that loop.
2033     This may cause unexpected results and the compiler will generate warnings
2034     about loop index shadowed variables.
2035     \end_layout
2036    
2037     \end_deeper
2038     \begin_layout List
2039     \labelwidthstring 00000.00000.00000.000
2040     Label
2041 jpye 1733 \begin_inset LatexCommand index
2042     name "label"
2043 johnpye 828
2044     \end_inset
2045    
2046     : One can label statements which define arithmetic relationships (objective
2047     functions, equalities, and inequalities) in ASCEND.
2048     Labeling is highly recommended because it makes models much more readable
2049     and more easily debugged.
2050     Labels are also necessary for relations which are going to be used in condition
2051     al modeling or differentiation functions.
2052     A label is a sequence of alphanumeric characters ending in a colon.
2053     An example of a labeled equation is:
2054     \end_layout
2055    
2056     \begin_deeper
2057     \begin_layout LyX-Code
2058     mass_balance: m_in = m_out;
2059     \end_layout
2060    
2061     \begin_layout Standard
2062     An example of a labeled objective function is:
2063     \end_layout
2064    
2065     \begin_layout LyX-Code
2066     obj1: MAXIMIZE revenue - cost;
2067     \end_layout
2068    
2069     \begin_layout Standard
2070     If a relation is defined within a FOR statement, it must have an array indexed
2071     label so that each instance created using the statement is distinguishable
2072     from the others.
2073     An example is:
2074     \end_layout
2075    
2076     \begin_layout LyX-Code
2077     FOR i IN components CREATE
2078     \end_layout
2079    
2080     \begin_layout LyX-Code
2081     equil[i]: y[i] = K[i]*x[i];
2082     \end_layout
2083    
2084     \begin_layout LyX-Code
2085     END FOR;
2086     \end_layout
2087    
2088     \begin_layout Standard
2089     The ASCEND interactive user interface identifies relationships by their
2090     labels.
2091     If one has not provided such a label, the system generates the label:
2092     \end_layout
2093    
2094     \begin_layout LyX-Code
2095    
2096     \emph on
2097     modelname_equationnumber
2098     \end_layout
2099    
2100     \begin_layout Standard
2101     where modelname and equationnumber are the name of the model and the equation
2102     number in the model.
2103     An example is
2104     \end_layout
2105    
2106     \begin_layout LyX-Code
2107     mixture_14
2108     \end_layout
2109    
2110     \begin_layout Standard
2111     for the unlabeled 14th relation in the mixture definition.
2112     If there is a conflict caused with an existing name, the generated name
2113     has enough letters added after equationnumber to make it a unique name.
2114     Remember that each model in a refinement hierarchy inherits the equations
2115     of its less refined ancestors, so the first equation appearing in the source
2116     code of a refining model may actually be the nth relation in that model.
2117     \end_layout
2118    
2119     \end_deeper
2120     \begin_layout List
2121     \labelwidthstring 00000.00000.00000.000
2122    
2123     \bar under
2124     Lists
2125     \bar default
2126    
2127 jpye 1733 \begin_inset LatexCommand index
2128     name "lists"
2129 johnpye 828
2130     \end_inset
2131    
2132     Often in a statement one can include a list of names or expression.
2133     A name list is one or more names where multiple list entries are separated
2134     from each other by commas.
2135     Examples of a list of names are:
2136     \end_layout
2137    
2138     \begin_deeper
2139     \begin_layout LyX-Code
2140     \align block
2141     T1, inlet_T, outlet_T
2142     \end_layout
2143    
2144     \begin_layout LyX-Code
2145     \align block
2146     y[components], y_in
2147     \end_layout
2148    
2149     \begin_layout LyX-Code
2150     \align block
2151     stage[1..n_stages]
2152     \end_layout
2153    
2154     \end_deeper
2155     \begin_layout List
2156     \labelwidthstring 00000.00000.00000.000
2157    
2158     \bar under
2159     Ordered\InsetSpace ~
2160     lists
2161 jpye 1733 \begin_inset LatexCommand index
2162     name "lists, ordered"
2163 johnpye 828
2164     \end_inset
2165    
2166    
2167 jpye 1733 \begin_inset LatexCommand index
2168     name "ordered lists"
2169 johnpye 828
2170     \end_inset
2171    
2172     :
2173     \bar default
2174     If the ordering of names in a list matters, that list is enclosed in ().
2175     Order matters in: calling externally defined methods or models, calling
2176     most real-valued functions, passing parameters to ASCEND models or methods,
2177     and declaring the controlling parameters that SELECT, SWITCH, and WHEN
2178     statements make decisions on.
2179     \end_layout
2180    
2181     \begin_deeper
2182 jpye 1384 \begin_layout Section
2183 johnpye 828 Basic Concepts
2184     \end_layout
2185    
2186     \end_deeper
2187     \begin_layout List
2188     \labelwidthstring 00000.00000.00000.000
2189    
2190     \bar under
2191     Instances
2192 jpye 1733 \begin_inset LatexCommand index
2193     name "instances"
2194 johnpye 828
2195     \end_inset
2196    
2197     \InsetSpace ~
2198     and\InsetSpace ~
2199     types
2200     \bar default
2201    
2202 jpye 1733 \begin_inset LatexCommand index
2203     name "types"
2204 johnpye 828
2205     \end_inset
2206    
2207     This is an opportune time to emphasize the distinction between the terms
2208     instance and type.
2209     A type in ASCEND is what we define when we declare an ASCEND model or atom.
2210     It is the formal definition of the attributes (parts) and attribute default
2211     values that an object will have if it is created using the type definition.
2212     Methods are associated with types.
2213     \end_layout
2214    
2215     \begin_deeper
2216     \begin_layout Standard
2217     In ASCEND there are two meanings (closely related) of an instance.
2218    
2219     \end_layout
2220    
2221     \begin_layout Itemize
2222     An instance is a named part that exists within a type definition.
2223    
2224     \end_layout
2225    
2226     \begin_layout Itemize
2227     An instance is a compiled object.
2228    
2229     \end_layout
2230    
2231     \begin_layout Standard
2232     If one is in the context of the ASCEND interface, the system compiles an
2233     instance of a model type to create an object with which one carries out
2234     computations.
2235     The system requires the user to give a simple name for this simulation
2236     instance.
2237     This name given is then the first part of the qualified name for all the
2238     parts of the compiled object.
2239     \end_layout
2240    
2241     \end_deeper
2242     \begin_layout List
2243     \labelwidthstring 00000.00000.00000.000
2244    
2245     \bar under
2246     Implicit\InsetSpace ~
2247     types
2248     \bar default
2249    
2250 jpye 1733 \begin_inset LatexCommand index
2251     name "types, implicit"
2252 johnpye 828
2253     \end_inset
2254    
2255    
2256 jpye 1733 \begin_inset LatexCommand index
2257     name "types, implicit"
2258 johnpye 828
2259     \end_inset
2260    
2261     It is possible to create an instance that does not have a corresponding
2262     type definition in the library.
2263 jpye 1384 The type of such an instance is said to be
2264     \series bold
2265     implicit
2266     \series default
2267    
2268     \begin_inset Foot
2269     status collapsed
2270    
2271     \begin_layout Standard
2272     (Some people use the word
2273     \emph on
2274     anonymous
2275     \emph default
2276    
2277 jpye 1733 \begin_inset LatexCommand index
2278     name "type, anonymous"
2279 johnpye 828
2280     \end_inset
2281    
2282    
2283 jpye 1733 \begin_inset LatexCommand index
2284     name "anonymous type"
2285 johnpye 828
2286     \end_inset
2287    
2288     .
2289     However, no computable type is anonymous and the implicit type of an instance
2290 jpye 1384 is theoretically computable)
2291     \end_layout
2292    
2293     \end_inset
2294    
2295     .
2296 johnpye 828 The simplest example of an implicit type is the type of an instance compiled
2297 jpye 1384 from the built-in definition
2298     \family sans
2299     integer_constant
2300     \family default
2301     .
2302 johnpye 828 For example:
2303     \end_layout
2304    
2305     \begin_deeper
2306     \begin_layout LyX-Code
2307     i, j IS_A integer_constant;
2308     \end_layout
2309    
2310     \begin_layout LyX-Code
2311     i:== 2;
2312     \end_layout
2313    
2314     \begin_layout LyX-Code
2315     j:== 3;
2316     \end_layout
2317    
2318     \begin_layout Standard
2319 jpye 1384 Instances
2320     \family typewriter
2321     i
2322     \family default
2323     and
2324     \family typewriter
2325     j
2326     \family default
2327     , though of the same formal type, are implicit type incompatible because
2328     they have been assigned distinct values.
2329 johnpye 828 \end_layout
2330    
2331     \begin_layout Standard
2332     Instances which are either formally or implicitly type incompatible cannot
2333     be merged.
2334     This will be discussed further in Section
2335 jpye 1733 \begin_inset LatexCommand vref
2336     reference "sec:x.3Declarative-statements"
2337 johnpye 828
2338     \end_inset
2339    
2340     .
2341     \end_layout
2342    
2343     \end_deeper
2344     \begin_layout List
2345     \labelwidthstring 00000.00000.00000.000
2346     Parsing
2347 jpye 1733 \begin_inset LatexCommand index
2348     name "parsing"
2349 johnpye 828
2350     \end_inset
2351    
2352     Most errors in the declaration of an ASCEND model can be caught at parse
2353     time because the object type of any well-formed name in an ASCEND definition
2354     can be resolved or proved ambiguous.
2355     We cannot prove at parse time whether a specific array element will exist,
2356     but we can know that should such an element exist, it must be of the type
2357     with which the array is defined.
2358    
2359     \end_layout
2360    
2361     \begin_deeper
2362     \begin_layout Standard
2363     Ambiguity is warned about loudly because it is caused by either misspelling
2364     or poor modeling style.
2365     The simplest example of ambiguity follows.
2366     \end_layout
2367    
2368     \begin_layout Standard
2369     Assume a type, stream, and a refinement of stream, heat_stream, which adds
2370 jpye 1384 the new variable
2371     \family typewriter
2372     H
2373     \family default
2374     .
2375 johnpye 828 Now, if we write:
2376     \end_layout
2377    
2378     \begin_layout LyX-Code
2379     MODEL mixer;
2380     \end_layout
2381    
2382     \begin_layout LyX-Code
2383     input[1..2] IS_A stream;
2384     \end_layout
2385    
2386     \begin_layout LyX-Code
2387     output IS_A heat_stream;
2388     \end_layout
2389    
2390     \begin_layout LyX-Code
2391     input[1].H + input[2].H = output.H;
2392     \end_layout
2393    
2394     \begin_layout LyX-Code
2395     END mixer;
2396     \end_layout
2397    
2398     \begin_layout Standard
2399     We see the parser can find the definition of H in the type heat_stream,
2400 jpye 1384 so
2401     \family typewriter
2402     output.H
2403     \family default
2404     is well defined.
2405     The author of the mixer model may intend to refine
2406     \family typewriter
2407     input[1]
2408     \family default
2409     and
2410     \family typewriter
2411     input[2]
2412     \family default
2413 johnpye 828 to be objects of different types, say steam_stream and electric_stream,
2414 jpye 1384 where each defines an
2415     \family typewriter
2416     H
2417     \family default
2418     suitable for use in the equation.
2419     The parser cannot read the authors mind, so it warns that
2420     \family typewriter
2421     input[1].H
2422     \family default
2423     and
2424     \family typewriter
2425     input[2].H
2426     \family default
2427     are ambiguous in the mixer definition.
2428 johnpye 828 The mixer model is not highly reusable except by the author, but sometimes
2429     reusability is not a high priority objective.
2430     The mixer definition is allowed, but it may cause problems in instantiation
2431     if the author has forgotten the assumption that is not explicitly stated
2432     in the model and neglects to refine the input streams appropriately.
2433     \end_layout
2434    
2435     \end_deeper
2436     \begin_layout List
2437     \labelwidthstring 00000.00000.00000.000
2438    
2439     \bar under
2440     Instantiation
2441     \bar default
2442    
2443 jpye 1733 \begin_inset LatexCommand index
2444     name "instantiation"
2445 johnpye 828
2446     \end_inset
2447    
2448     Creating an simulation based on a type definition is a multi-phase
2449 jpye 1733 \begin_inset LatexCommand index
2450     name "multi-phase"
2451 johnpye 828
2452     \end_inset
2453    
2454     process called compiling
2455 jpye 1733 \begin_inset LatexCommand index
2456     name "compiling"
2457 johnpye 828
2458     \end_inset
2459    
2460     (or instantiation).
2461     When an instantiation cannot be completed because some structural parameter
2462     (a symbol_constant, real_constant, boolean_constant, integer_constant,
2463     or set) does not have a value there will be PENDING
2464 jpye 1733 \begin_inset LatexCommand index
2465     name "PENDING"
2466 johnpye 828
2467     \end_inset
2468    
2469     statements.
2470     The user interface will warn that something is incomplete.
2471     \end_layout
2472    
2473     \begin_deeper
2474     \begin_layout Standard
2475     In phase
2476 jpye 1733 \begin_inset LatexCommand index
2477     name "phases, compiler"
2478 johnpye 828
2479     \end_inset
2480    
2481     1 all statements that create instance structures or assign constant values
2482     are executed.
2483     This phase theoretically requires an infinite number of passes through
2484     the structural statements of a definition.
2485     We allow a maximum of 5 and have never needed more than 3.
2486     There may be pending statements at the end of phase 1.
2487     The compiler or interface will issue warnings about pending statements,
2488     starting with warnings about unassigned constants.
2489     \end_layout
2490    
2491     \begin_layout Standard
2492     Phase 2 compiles as many real arithmetic relation definitions as possible.
2493     Some relations may be impossible to compile because the constants or sets
2494     they depend on do not have values assigned.
2495     Other relations may be impossible because they reference variables that
2496     do not exist.
2497     This is determined in a single pass.
2498     \end_layout
2499    
2500     \begin_layout Standard
2501     Phase 3 compiles as many logical arithmetic relation definitions as possible.
2502     Some relations may be impossible to compile because the constants or sets
2503     they depend on do not have values assigned.
2504     Other relations may be impossible because they reference real arithmetic
2505     relations that do not exist.
2506     This is determined in a single pass.
2507     \end_layout
2508    
2509     \begin_layout Standard
2510 jpye 1384 Phase 4 compiles as many conditional programming statements (
2511     \family sans
2512     WHEN
2513     \family default
2514     s) as possible.
2515     Some
2516     \family sans
2517     WHEN
2518     \family default
2519     relations may be impossible to compile because the discrete variables,
2520     models, or relations they depend on do not exist.
2521 johnpye 828 This is determined in a single pass.
2522     \end_layout
2523    
2524     \begin_layout Standard
2525     Phase 5 executes the variable defaulting statements made in the declarative
2526 jpye 1384 section of each model
2527     \emph on
2528     if and only if
2529     \emph default
2530     there are no pending statements from phases 1-4 anywhere in the simulation.
2531 johnpye 828 \end_layout
2532    
2533     \end_deeper
2534     \begin_layout List
2535     \labelwidthstring 00000.00000.00000.000
2536     default_self
2537 jpye 1733 \begin_inset LatexCommand index
2538     name "default\\_self"
2539 johnpye 828
2540     \end_inset
2541    
2542     After all phases are done, the method default_self is called in the top-most
2543     model of the simulation, if this method exists.
2544     \end_layout
2545    
2546     \begin_deeper
2547     \begin_layout Standard
2548     The first occurrence of each impossible statement will be explained during
2549     a failed compilation.
2550     Impossible statements include:
2551     \end_layout
2552    
2553     \begin_layout Itemize
2554     Relations containing undefinable variables (often misspellings).
2555     \end_layout
2556    
2557     \begin_layout Itemize
2558     Assignments that are dimensionally inconsistent or containing mismatched
2559     types.
2560     \end_layout
2561    
2562     \begin_layout Itemize
2563     Structure building or modifying statements that refer to model parts which
2564     cannot exist or that require a type-incompatible argument, refinement,
2565     or merge.
2566     \end_layout
2567    
2568 jpye 1384 \begin_layout Chapter
2569 johnpye 828 Data Type Declarations
2570 jpye 1733 \begin_inset LatexCommand index
2571     name "data type declarations"
2572 johnpye 828
2573     \end_inset
2574    
2575    
2576     \end_layout
2577    
2578     \begin_layout Standard
2579     In the spectrum of OO languages, ASCEND is best considered as being class-based
2580 jpye 1733 \begin_inset LatexCommand index
2581     name "class-based"
2582 johnpye 828
2583     \end_inset
2584    
2585     , though it is rather more a hybrid.
2586 jpye 1384 We have atom and model definitions, called
2587     \series bold
2588     types
2589     \series default
2590     , and the compiled objects themselves, called
2591     \series bold
2592     instances
2593     \series default
2594     .
2595 johnpye 828 ASCEND instances have a record of what type they were constructed from.
2596     \end_layout
2597    
2598     \end_deeper
2599     \begin_layout List
2600     \labelwidthstring 00000.00000.00000.000
2601    
2602     \bar under
2603     Type\InsetSpace ~
2604     qualifiers
2605 jpye 1733 \begin_inset LatexCommand index
2606     name "type qualifiers"
2607 johnpye 828
2608     \end_inset
2609    
2610     :
2611     \end_layout
2612    
2613     \begin_layout List
2614     \labelwidthstring 00000.00000.00000.000
2615 jpye 1384
2616     \family sans
2617 johnpye 828 UNIVERSAL
2618 jpye 1384 \family default
2619    
2620 jpye 1733 \begin_inset LatexCommand index
2621     name "UNIVERSAL"
2622 johnpye 828
2623     \end_inset
2624    
2625 jpye 1384 Universal is an optional modifier of all
2626     \family sans
2627     ATOM
2628     \family default
2629     ,
2630     \family sans
2631     CONSTANT
2632     \family default
2633     and
2634     \family sans
2635     MODEL
2636     \family default
2637     definitions.
2638     If
2639     \family sans
2640     UNIVERSAL
2641     \family default
2642     precedes the definition, then
2643     \emph on
2644     all
2645     \emph default
2646     instances of that type will actually refer to the first instance of the
2647     type that is created.
2648 johnpye 828 This saves memory and ensures global consistency of data.
2649    
2650     \end_layout
2651    
2652     \begin_deeper
2653     \begin_layout Standard
2654     Examples of universal type definitions are
2655     \end_layout
2656    
2657     \begin_layout LyX-Code
2658     UNIVERSAL MODEL methane
2659     \end_layout
2660    
2661     \begin_layout LyX-Code
2662     REFINES generic_component_model;
2663     \end_layout
2664    
2665     \begin_layout LyX-Code
2666     UNIVERSAL CONSTANT circle_constant
2667     \end_layout
2668    
2669     \begin_layout LyX-Code
2670     REFINES real_constant :== 1{PI};
2671     \end_layout
2672    
2673     \begin_layout LyX-Code
2674     UNIVERSAL ATOM counter_1
2675     \end_layout
2676    
2677     \begin_layout LyX-Code
2678     REFINES integer;
2679     \end_layout
2680    
2681     \end_deeper
2682     \begin_layout List
2683     \labelwidthstring 00000.00000.00000.000
2684     Tip:\InsetSpace ~
2685     Do\InsetSpace ~
2686     not\InsetSpace ~
2687     use\InsetSpace ~
2688 jpye 1384
2689     \family sans
2690     UNIVERSAL
2691     \family default
2692     \InsetSpace ~
2693 johnpye 828 variables\InsetSpace ~
2694     in\InsetSpace ~
2695     relations.
2696     \end_layout
2697    
2698     \begin_deeper
2699     \begin_layout Standard
2700 jpye 1384 It is important to note that, because
2701     \emph on
2702     variables
2703     \emph default
2704     must store information about which relations they occur in, it is a very
2705     bad idea to use
2706     \family sans
2707     UNIVERSAL
2708     \family default
2709     typed variables in relations.
2710 johnpye 828 The construction and maintenance of the relation list becomes very expensive
2711     for universal variables.
2712 jpye 1384
2713     \family sans
2714     UNIVERSAL
2715     \family default
2716    
2717     \emph on
2718     constants
2719     \emph default
2720     are fine to use, though, because there are no relation links for constants.
2721 johnpye 828 \end_layout
2722    
2723 jpye 1384 \begin_layout Section
2724 johnpye 828 Models
2725     \end_layout
2726    
2727     \end_deeper
2728     \begin_layout List
2729     \labelwidthstring 00000.00000.00000.000
2730 jpye 1384
2731     \family sans
2732 johnpye 828 MODEL
2733 jpye 1384 \family default
2734    
2735 jpye 1733 \begin_inset LatexCommand index
2736     name "MODEL"
2737 johnpye 828
2738     \end_inset
2739    
2740     An ASCEND model has a declarative part and an optional procedural part
2741     headed by the METHODS word.
2742     Models are essentially containers for variables and relations.
2743     We will explain the various statements that can be made within models in
2744     Section
2745 jpye 1733 \begin_inset LatexCommand vref
2746     reference "sec:x.3Declarative-statements"
2747 johnpye 828
2748     \end_inset
2749    
2750     and Section
2751 jpye 1733 \begin_inset LatexCommand vref
2752     reference "sec:x.4Procedural-statements"
2753 johnpye 828
2754     \end_inset
2755    
2756     .
2757     \end_layout
2758    
2759     \begin_layout Standard
2760     Simple\InsetSpace ~
2761     models
2762 jpye 1733 \begin_inset LatexCommand index
2763     name "models, simple"
2764 johnpye 828
2765     \end_inset
2766    
2767     :
2768     \end_layout
2769    
2770     \begin_layout List
2771     \labelwidthstring 00000.00000.00000.000
2772     foo
2773     \family typewriter
2774     \InsetSpace ~
2775     \InsetSpace ~
2776     \InsetSpace ~
2777     \InsetSpace ~
2778     MODEL foo;
2779     \end_layout
2780    
2781     \begin_deeper
2782     \begin_layout LyX-Code
2783     (* statements about foo go here*)
2784     \end_layout
2785    
2786     \begin_layout LyX-Code
2787     METHODS
2788     \end_layout
2789    
2790     \begin_layout LyX-Code
2791     (* METHODs for foo go here*)
2792     \end_layout
2793    
2794     \begin_layout LyX-Code
2795     END foo;
2796     \end_layout
2797    
2798     \end_deeper
2799     \begin_layout List
2800     \labelwidthstring 00000.00000.00000.000
2801     bar
2802     \family typewriter
2803     \InsetSpace ~
2804     \InsetSpace ~
2805     \InsetSpace ~
2806     \InsetSpace ~
2807     MODEL bar REFINES foo;
2808     \end_layout
2809    
2810     \begin_deeper
2811     \begin_layout LyX-Code
2812     (*additional statements about foo *)
2813     \end_layout
2814    
2815     \begin_layout LyX-Code
2816     METHODS
2817     \end_layout
2818    
2819     \begin_layout LyX-Code
2820     (* additional METHODs for bar *)
2821     \end_layout
2822    
2823     \begin_layout LyX-Code
2824     END bar;
2825     \end_layout
2826    
2827     \end_deeper
2828     \begin_layout List
2829     \labelwidthstring 00000.00000.00000.000
2830    
2831     \bar under
2832     Parameterized\InsetSpace ~
2833     Models
2834     \bar default
2835    
2836 jpye 1733 \begin_inset LatexCommand index
2837     name "models, parameterized"
2838 johnpye 828
2839     \end_inset
2840    
2841 jpye 1384 Parameterizing models makes them easier to understand and faster for the
2842     system to compile.
2843 johnpye 828 The syntax for a parameterized model vaguely resembles a function call
2844     in imperative languages, but it is NOT.
2845     When constructing a reusable model, all the constants that determine the
2846     sizes of arrays and other structures should be declared in the parameter
2847     list so that
2848     \end_layout
2849    
2850     \begin_deeper
2851     \begin_layout Itemize
2852     the user knows what is required to reuse the model.
2853     \end_layout
2854    
2855     \begin_layout Itemize
2856     the compiler knows what values must be set before it should bother attempting
2857     to compile the model.
2858     \end_layout
2859    
2860     \begin_layout Standard
2861     There is no reason that other items could not also go in the parameter list,
2862     such as key variables which might be considered inputs or outputs or control
2863     parameters in the mathematical application of the model.
2864     A simple example of parameterization would be:
2865     \end_layout
2866    
2867     \end_deeper
2868     \begin_layout List
2869     \labelwidthstring 00000.00000.00000.000
2870     column(n,s)
2871     \end_layout
2872    
2873     \begin_deeper
2874     \begin_layout LyX-Code
2875     MODEL column(
2876     \end_layout
2877    
2878     \begin_layout LyX-Code
2879     ntrays WILL_BE integer_constant;
2880     \end_layout
2881    
2882     \begin_layout LyX-Code
2883     components IS_A set of symbol_constant;
2884     \end_layout
2885    
2886     \begin_layout LyX-Code
2887     );
2888     \end_layout
2889    
2890     \begin_layout LyX-Code
2891     stage[1..ntrays] IS_A simple_tray;
2892     \end_layout
2893    
2894     \begin_layout LyX-Code
2895     END column;
2896     \end_layout
2897    
2898     \end_deeper
2899     \begin_layout List
2900     \labelwidthstring 00000.00000.00000.000
2901     flowsheet
2902     \end_layout
2903    
2904     \begin_deeper
2905     \begin_layout LyX-Code
2906     MODEL flowsheet;
2907     \end_layout
2908    
2909     \begin_layout LyX-Code
2910     tower4size IS_A integer_constant;
2911     \end_layout
2912    
2913     \begin_layout LyX-Code
2914     tower4size :== 22;
2915     \end_layout
2916    
2917     \begin_layout LyX-Code
2918     ct IS_A column(tower4size,[c5,c6]);
2919     \end_layout
2920    
2921     \begin_layout LyX-Code
2922     (* additional flowsheet statements *)
2923     \end_layout
2924    
2925     \begin_layout LyX-Code
2926     END flowsheet;
2927     \end_layout
2928    
2929     \begin_layout Standard
2930     In this example, the column model takes the first argument, ntrays, by reference.
2931 jpye 1733 That is,
2932 jpye 1384 \family typewriter
2933 jpye 1733 ct.ntrays
2934 jpye 1384 \family default
2935     is an alias for the flowsheet instance
2936     \family typewriter
2937     tower4size
2938     \family default
2939     .
2940 johnpye 828
2941 jpye 1384 \family typewriter
2942     tower4size
2943     \family default
2944     must be compiled and assigned a value before we will attempt to compile
2945     the column model instance
2946     \family typewriter
2947     ct
2948     \family default
2949     .
2950     The second argument is taken by value,
2951     \family typewriter
2952     [c5,c6]
2953     \family default
2954     , and assigned to components, a column part that was declared with
2955     \family sans
2956     IS_A
2957     \family default
2958     in the parameter list.
2959     There is only one name for this set,
2960     \family typewriter
2961     ct.components
2962     \family default
2963     .
2964     Note that in the
2965     \family typewriter
2966     flowsheet
2967     \family default
2968     model there is no part that is a set of
2969     \family sans
2970     symbol_constant
2971     \family default
2972     .
2973    
2974 johnpye 828 \end_layout
2975    
2976     \begin_layout Standard
2977     The use of parameters in ASCEND modeling requires some thought, and we will
2978     present that set of thoughts in Section
2979 jpye 1733 \begin_inset LatexCommand vref
2980     reference "sec:x.5Parameterized-models"
2981 johnpye 828
2982     \end_inset
2983    
2984     .
2985     Beginners may wish to create new models without parameters until they are
2986     comfortable using the existing parameterized library definitions.
2987     Parameters are intended to support model reuse and efficient compilation
2988     which are not issues in the very earliest phase of developing novel models.
2989     \end_layout
2990    
2991 jpye 1384 \begin_layout Section
2992 johnpye 828 Sets
2993 jpye 1733 \begin_inset LatexCommand index
2994     name "sets"
2995 johnpye 828
2996     \end_inset
2997    
2998    
2999 jpye 1733 \begin_inset LatexCommand label
3000     name "sub:x.2.2Sets"
3001 johnpye 828
3002     \end_inset
3003    
3004    
3005     \end_layout
3006    
3007     \begin_layout Standard
3008     Arrays in ASCEND, as already discussed in Section
3009 jpye 1733 \begin_inset LatexCommand vref
3010     reference "sub:x.1.2Basic-Elements"
3011 johnpye 828
3012     \end_inset
3013    
3014     , are defined over sets.
3015     A set is simply an instance with a set value.
3016 jpye 1384 The elements of sets are
3017     \emph on
3018     not
3019     \emph default
3020     instances or sets.
3021 johnpye 828 \end_layout
3022    
3023     \end_deeper
3024     \begin_layout List
3025     \labelwidthstring 00000.00000.00000.000
3026    
3027     \bar under
3028     Set\InsetSpace ~
3029     Declaration:
3030     \bar default
3031     A set is made of either symbol_constants or integer_constants, so a set
3032     object is declared in one of two ways:
3033     \end_layout
3034    
3035     \begin_deeper
3036     \begin_layout LyX-Code
3037     my_integer_set IS_A set OF integer_constant;
3038     \end_layout
3039    
3040     \begin_layout Standard
3041     or
3042     \end_layout
3043    
3044     \begin_layout LyX-Code
3045     my_symbol_set IS_A set OF symbol_constant;
3046     \end_layout
3047    
3048     \end_deeper
3049     \begin_layout List
3050     \labelwidthstring 00000.00000.00000.000
3051 jpye 1384
3052     \family typewriter
3053 johnpye 828 :==
3054 jpye 1384 \family default
3055    
3056 jpye 1733 \begin_inset LatexCommand index
3057     name ":=="
3058 johnpye 828
3059     \end_inset
3060    
3061     A set is assigned a value like so:
3062     \end_layout
3063    
3064     \begin_deeper
3065     \begin_layout LyX-Code
3066     my_integer_set :== [1,4];
3067     \end_layout
3068    
3069     \begin_layout Standard
3070     The RHS of such an assignment must be either the name of another set instance
3071     or an expression enclosed in square brackets and made up of only set operators,
3072     other sets, and the names of integer_constants or symbol_constants.
3073     Sets can only be assigned once.
3074     \end_layout
3075    
3076     \end_deeper
3077     \begin_layout List
3078     \labelwidthstring 00000.00000.00000.000
3079    
3080     \bar under
3081     Set\InsetSpace ~
3082     Operations
3083     \bar default
3084 jpye 1384
3085     \family sans
3086     UNION
3087     \family default
3088    
3089 jpye 1733 \begin_inset LatexCommand index
3090     name "UNION"
3091 johnpye 828
3092     \end_inset
3093    
3094 jpye 1384
3095     \family typewriter
3096 johnpye 828 [setlist]
3097     \end_layout
3098    
3099     \begin_deeper
3100     \begin_layout Standard
3101     A function taken over a list of sets.
3102     The result is the set that includes all the members of all the sets in
3103     the list.
3104 jpye 1384 Note that the result of the
3105     \family sans
3106     UNION
3107     \family default
3108     operation is an unordered set and the argument order to the union function
3109     does not matter.
3110 johnpye 828 The syntax is:
3111     \end_layout
3112    
3113     \end_deeper
3114     \begin_layout List
3115     \labelwidthstring 00000.00000.00000.000
3116     +
3117 jpye 1733 \begin_inset LatexCommand index
3118     name "+, sets"
3119 johnpye 828
3120     \end_inset
3121    
3122 jpye 1384
3123     \family typewriter
3124     UNION[list_of_sets]
3125 johnpye 828 \end_layout
3126    
3127     \begin_layout List
3128     \labelwidthstring 00000.00000.00000.000
3129 jpye 1384
3130     \family typewriter
3131     A+B
3132     \family default
3133     \InsetSpace ~
3134 johnpye 828 is\InsetSpace ~
3135     shorthand\InsetSpace ~
3136 jpye 1384 for
3137     \family typewriter
3138     UNION[A,B]
3139 johnpye 828 \end_layout
3140    
3141     \begin_deeper
3142     \begin_layout Standard
3143     Consider the following sets for the examples to follow.
3144     \end_layout
3145    
3146     \begin_layout LyX-Code
3147     A := [1, 2, 3, 5, 9];
3148     \end_layout
3149    
3150     \begin_layout LyX-Code
3151     B := [2, 4, 6, 8];
3152     \end_layout
3153    
3154     \begin_layout Standard
3155 jpye 1384 Then
3156     \family typewriter
3157     UNION[A, B]
3158     \family default
3159     is equal to the set
3160     \family typewriter
3161     [1, 2, 3, 4, 5, 6, 8, 9]
3162     \family default
3163     which equals
3164     \family typewriter
3165     [1..6, 8, 9]
3166     \family default
3167     which equals
3168     \family typewriter
3169     [[1..9] - [7]]
3170     \family default
3171     .
3172 johnpye 828 \end_layout
3173    
3174     \end_deeper
3175     \begin_layout List
3176     \labelwidthstring 00000.00000.00000.000
3177 jpye 1384
3178     \family sans
3179 johnpye 828 INTERSECTION
3180 jpye 1384 \family default
3181    
3182 jpye 1733 \begin_inset LatexCommand index
3183     name "INTERSECTION"
3184 johnpye 828
3185     \end_inset
3186    
3187     [] INTERSECTION[list of set expressions].
3188     Finds the intersection (and) of the sets listed.
3189    
3190     \end_layout
3191    
3192     \begin_layout List
3193     \labelwidthstring 00000.00000.00000.000
3194     *
3195 jpye 1733 \begin_inset LatexCommand index
3196     name "*, sets"
3197 johnpye 828
3198     \end_inset
3199    
3200 jpye 1384 Equivalent to
3201     \family sans
3202     INTERSECTION
3203     \family typewriter
3204     [list_of_sets]
3205     \family default
3206     .
3207 johnpye 828 \end_layout
3208    
3209     \begin_layout List
3210     \labelwidthstring 00000.00000.00000.000
3211 jpye 1384
3212     \family typewriter
3213     A*B
3214     \family default
3215     \InsetSpace ~
3216 johnpye 828 is\InsetSpace ~
3217     shorthand\InsetSpace ~
3218     for\InsetSpace ~
3219 jpye 1384 I
3220     \family typewriter
3221     NTERSECTION[A,B]
3222 johnpye 828 \end_layout
3223    
3224     \begin_deeper
3225     \begin_layout Standard
3226 jpye 1384 For the sets A and B defined just above,
3227     \family typewriter
3228     INTERSECTION[A, B]
3229     \family default
3230     is the set
3231     \family typewriter
3232     [2]
3233     \family default
3234     .
3235     The
3236     \family typewriter
3237     *
3238     \family default
3239     shorthand for intersection is
3240     \emph on
3241     not
3242     \emph default
3243     recommended for use except in libraries no one will look at.
3244 johnpye 828 \end_layout
3245    
3246     \end_deeper
3247     \begin_layout List
3248     \labelwidthstring 00000.00000.00000.000
3249     Set\InsetSpace ~
3250     difference
3251 jpye 1733 \begin_inset LatexCommand index
3252     name "set difference"
3253 johnpye 828
3254     \end_inset
3255    
3256     : One can subtract one set from another.
3257     The result is the first set less any members in the set union of the first
3258     and second set.
3259     The syntax is
3260     \end_layout
3261    
3262 jpye 1384 \begin_deeper
3263     \begin_layout LyX-Code
3264    
3265     \family typewriter
3266 jpye 1733 first_set
3267 jpye 1384 \family default
3268 jpye 1733 -
3269     \begin_inset LatexCommand index
3270     name "-, sets"
3271 johnpye 828
3272     \end_inset
3273    
3274 jpye 1733
3275 johnpye 828 \family typewriter
3276 jpye 1733 second_set
3277 johnpye 828 \end_layout
3278    
3279     \begin_layout Standard
3280 jpye 1384 For the sets
3281     \family typewriter
3282     A
3283     \family default
3284     and
3285     \family typewriter
3286     B
3287     \family default
3288     defined above, the set difference
3289     \family typewriter
3290     A - B
3291     \family default
3292     is the set
3293     \family typewriter
3294     [1, 3, 5, 9]
3295     \family default
3296     while the set difference
3297     \family typewriter
3298     B - A
3299     \family default
3300     is the set
3301     \family typewriter
3302     [4, 6, 8]
3303     \family default
3304     .
3305 johnpye 828 \end_layout
3306    
3307     \end_deeper
3308     \begin_layout List
3309     \labelwidthstring 00000.00000.00000.000
3310 jpye 1384
3311     \family sans
3312 johnpye 828 CARD
3313 jpye 1384 \family default
3314    
3315 jpye 1733 \begin_inset LatexCommand index
3316     name "CARD"
3317 johnpye 828
3318     \end_inset
3319    
3320     [set] Cardinality
3321 jpye 1733 \begin_inset LatexCommand index
3322     name "cardinality"
3323 johnpye 828
3324     \end_inset
3325    
3326     .
3327     Returns an integer constant value that is the number of items in the set.
3328     \end_layout
3329    
3330     \begin_layout List
3331     \labelwidthstring 00000.00000.00000.000
3332 jpye 1384
3333     \family sans
3334 johnpye 828 CHOICE
3335 jpye 1384 \family default
3336    
3337 jpye 1733 \begin_inset LatexCommand index
3338     name "CHOICE"
3339 johnpye 828
3340     \end_inset
3341    
3342     [set] Choose one.
3343 jpye 1384 The result of running the
3344     \family sans
3345     CHOICE
3346     \family default
3347     function over a set is an arbitrary (but consistent: for any set instance
3348     you always get the same result) single element of that set.
3349 johnpye 828
3350     \end_layout
3351    
3352     \begin_deeper
3353     \begin_layout Standard
3354 jpye 1384 Running
3355     \family typewriter
3356     CHOICE[A]
3357     \family default
3358     gives any member from the set A.
3359 johnpye 828 The result is a member, not a set.
3360     To make the result into a set, it must be enclosed in square brackets.
3361 jpye 1384 Thus
3362     \family typewriter
3363     [CHOICE[A]]
3364     \family default
3365     is a set with a single element arbitrarily chosen from the set A.
3366 johnpye 828 Good modelers do not leave modeling decisions to the compiler; they do
3367 jpye 1384 not use
3368     \family sans
3369     CHOICE
3370     \family default
3371     .
3372 johnpye 828 We are stuck with it for historical reasons.
3373     \end_layout
3374    
3375     \begin_layout Standard
3376     To reduce a set by one element, one can use the following
3377     \end_layout
3378    
3379     \begin_layout LyX-Code
3380     A_less_one IS_A set OF integer;
3381     \end_layout
3382    
3383     \begin_layout LyX-Code
3384     A_less_one :== A - [CHOICE[A]];
3385     \end_layout
3386    
3387     \end_deeper
3388     \begin_layout List
3389     \labelwidthstring 00000.00000.00000.000
3390 jpye 1384
3391     \family sans
3392 johnpye 828 IN
3393 jpye 1384 \family default
3394    
3395 jpye 1733 \begin_inset LatexCommand index
3396     name "IN"
3397 johnpye 828
3398     \end_inset
3399    
3400 jpye 1384
3401     \family typewriter
3402     lhs IN rhs
3403     \family default
3404     can only be well explained by examples.
3405    
3406     \family sans
3407     IN
3408     \family default
3409     is used in index expressions.
3410     If
3411     \family typewriter
3412     lhs
3413     \family default
3414     is a simple and not previously defined name, it is created as a temporary
3415     loop index which will take on the values of the rhs set definition.
3416     If lhs is something that already exists, the result of
3417     \family typewriter
3418     lhs IN rhs
3419     \family default
3420     is a boolean value; stare at the model
3421     \family typewriter
3422     set_example
3423     \family default
3424     below which demonstrates both
3425     \family sans
3426     IN
3427     \family default
3428     and
3429     \family sans
3430     SUCH_THAT
3431     \family default
3432     .
3433     If you still are not satisfied, you might examine [[westerbergksets]]
3434     \begin_inset Note Note
3435     status open
3436    
3437     \begin_layout Standard
3438     fix this reference
3439 johnpye 828 \end_layout
3440    
3441 jpye 1384 \end_inset
3442    
3443     .
3444     \end_layout
3445    
3446 johnpye 828 \begin_layout List
3447     \labelwidthstring 00000.00000.00000.000
3448 jpye 1384
3449     \family sans
3450 johnpye 828 SUCH_THAT
3451 jpye 1384 \family default
3452    
3453 jpye 1733 \begin_inset LatexCommand index
3454     name "SUCH\\_THAT"
3455 johnpye 828
3456     \end_inset
3457    
3458 jpye 1384 Set expressions can be rather clever.
3459 johnpye 828 We will give a detailed example from chemistry because unordered sets are
3460     unfamiliar to most people and set arithmetic is quite powerful.
3461     In this example we see arrays of sets and sparse arrays.
3462    
3463     \end_layout
3464    
3465     \begin_layout LyX-Code
3466     MODEL set_example;
3467     \end_layout
3468    
3469     \begin_layout LyX-Code
3470 jpye 1384 (* we define a sparse matrix of reaction
3471 johnpye 828 \end_layout
3472    
3473     \begin_layout LyX-Code
3474 jpye 1384 coefficient information and the species
3475 johnpye 828 \end_layout
3476    
3477     \begin_layout LyX-Code
3478 jpye 1384 balance equations.
3479 johnpye 828 *)
3480     \end_layout
3481    
3482     \begin_layout LyX-Code
3483 jpye 1384 rxns IS_A set OF integer_constant;
3484 johnpye 828 \end_layout
3485    
3486     \begin_layout LyX-Code
3487 jpye 1384 rxns :== [1..3];
3488 johnpye 828 \end_layout
3489    
3490     \begin_layout LyX-Code
3491 jpye 1384 species IS_A set OF symbol_constant;
3492 johnpye 828 \end_layout
3493    
3494     \begin_layout LyX-Code
3495 jpye 1384 species :== ['A','B','C','D'];
3496 johnpye 828 \end_layout
3497    
3498     \begin_layout LyX-Code
3499 jpye 1384 reactants[rxns] IS_A set OF symbol_constant; (* species
3500 johnpye 828 \end_layout
3501    
3502     \begin_layout LyX-Code
3503 jpye 1384 in each rxn_j *)
3504 johnpye 828 \end_layout
3505    
3506     \begin_layout LyX-Code
3507 jpye 1384 reactants[1] :== ['A','B','C'];
3508 johnpye 828 \end_layout
3509    
3510     \begin_layout LyX-Code
3511 jpye 1384 reactants[2] :== ['A','C'];
3512 johnpye 828 \end_layout
3513    
3514     \begin_layout LyX-Code
3515 jpye 1384 reactants[3] :== ['A','B','D'];
3516 johnpye 828 \end_layout
3517    
3518     \begin_layout LyX-Code
3519 jpye 1384 reactions[species] IS_A set OF integer_constant;
3520 johnpye 828 \end_layout
3521    
3522     \begin_layout LyX-Code
3523 jpye 1384 FOR i IN species CREATE (* rxns for each species i *)
3524 johnpye 828 \end_layout
3525    
3526     \begin_layout LyX-Code
3527 jpye 1384 reactions[i] :== [j IN rxns SUCH_THAT i IN reactants[j]];
3528 johnpye 828 \end_layout
3529    
3530     \begin_layout LyX-Code
3531 jpye 1384 END FOR;
3532 johnpye 828 \end_layout
3533    
3534     \begin_layout LyX-Code
3535 jpye 1384 (* Define sparse stoichiometric matrix.
3536 johnpye 828 Values of eta_ij
3537     \end_layout
3538    
3539     \begin_layout LyX-Code
3540 jpye 1384 set later.*)
3541 johnpye 828 \end_layout
3542    
3543     \begin_layout LyX-Code
3544 jpye 1384 FOR j IN rxns CREATE
3545 johnpye 828 \end_layout
3546    
3547     \begin_layout LyX-Code
3548 jpye 1384 FOR i IN reactants[j] CREATE
3549 johnpye 828 \end_layout
3550    
3551     \begin_layout LyX-Code
3552 jpye 1384 (* eta_ij --> mole i/mole rxn j*)
3553 johnpye 828 \end_layout
3554    
3555     \begin_layout LyX-Code
3556 jpye 1384 eta[i][j] IS_A real_constant;
3557 johnpye 828 \end_layout
3558    
3559     \begin_layout LyX-Code
3560 jpye 1384 END FOR;
3561 johnpye 828 \end_layout
3562    
3563     \begin_layout LyX-Code
3564 jpye 1384 END FOR;
3565 johnpye 828 \end_layout
3566    
3567     \begin_layout LyX-Code
3568 jpye 1384 production[species] IS_A molar_rate;
3569 johnpye 828 \end_layout
3570    
3571     \begin_layout LyX-Code
3572 jpye 1384 rate[rxns] IS_A molar_rate; (* mole rxn j/time *)
3573 johnpye 828 \end_layout
3574    
3575     \begin_layout LyX-Code
3576 jpye 1384 FOR i IN species CREATE
3577 johnpye 828 \end_layout
3578    
3579     \begin_layout LyX-Code
3580 jpye 1384 gen_eqn[i]: production[i] =
3581 johnpye 828 \end_layout
3582    
3583     \begin_layout LyX-Code
3584 jpye 1384 SUM[eta[i][j]*rate[j] | j IN reactions[i]];
3585 johnpye 828 \end_layout
3586    
3587     \begin_layout LyX-Code
3588 jpye 1384 END FOR;
3589 johnpye 828 \end_layout
3590    
3591     \begin_layout LyX-Code
3592     END set_example;
3593     \end_layout
3594    
3595     \begin_layout List
3596     \labelwidthstring 00000.00000.00000.000
3597 jpye 1384 "
3598     \family typewriter
3599     |
3600     \family default
3601    
3602 jpye 1733 \begin_inset LatexCommand index
3603     name "|"
3604 johnpye 828
3605     \end_inset
3606    
3607 jpye 1384 " is shorthand for
3608     \family sans
3609     SUCH_THAT
3610     \family default
3611     .
3612 johnpye 828 \end_layout
3613    
3614     \begin_deeper
3615     \begin_layout Standard
3616 jpye 1384 The array
3617     \family typewriter
3618     eta
3619     \family default
3620     has only 8 elements, and we defined those elements in a set for each reaction.
3621     The equation needs to know about the set of reactions for a species
3622     \family typewriter
3623     i
3624     \family default
3625     , and that set is calculated automatically in the models first
3626     \family sans
3627     FOR/CREATE
3628     \family default
3629 johnpye 828 statement.
3630    
3631     \end_layout
3632    
3633 jpye 1384 \begin_layout Standard
3634     The
3635     \family typewriter
3636 johnpye 828 |
3637 jpye 1384 \family default
3638     symbol is the ASCEND III notation for
3639     \family sans
3640     SUCH_THAT
3641     \family default
3642     .
3643     We noted that "
3644     \family typewriter
3645     |
3646     \family default
3647     " is often read as "for all", which is different in that "for all" makes
3648     one think of a
3649     \family sans
3650     FOR
3651     \family default
3652     loop where the loop index is on the left of an
3653     \family sans
3654     IN
3655     \family default
3656     operator.
3657     For example, the
3658     \family typewriter
3659     j
3660     \family default
3661     loop in the
3662     \family sans
3663     SUM
3664     \family default
3665     of
3666     \family typewriter
3667     gen_eqn[i]
3668     \family default
3669     above.
3670 johnpye 828
3671     \end_layout
3672    
3673 jpye 1384 \begin_layout Section
3674 johnpye 828 Constants
3675 jpye 1733 \begin_inset LatexCommand index
3676     name "constants"
3677 johnpye 828
3678     \end_inset
3679    
3680    
3681     \end_layout
3682    
3683     \begin_layout Standard
3684     ASCEND supports real, integer, boolean and character string constants.
3685     Constants in ASCEND do not have any attributes other than their value.
3686     Constants are scalar quantities that can be assigned exactly once.
3687 jpye 1384 Constants may only be assigned using the
3688     \family typewriter
3689     :==
3690     \family default
3691     operator and the RHS expression they are assigned from must itself be constant.
3692 johnpye 828 Constants do not have subparts.
3693     Integer and symbol constants may be used in determining the definitions
3694     of sets.
3695    
3696     \end_layout
3697    
3698     \begin_layout Standard
3699     Explicit refinements of the built-in constant types may be defined as exemplifie
3700     d in the description of real_constant.
3701     Implicit type refinements may be done by instantiating an incompletely
3702     defined constant and assigning its final value.
3703    
3704     \end_layout
3705    
3706     \begin_layout Standard
3707     Sets could be considered constant because they are assigned only once, however
3708     sets are described separately because they are not quite scalar quantities.
3709     \end_layout
3710    
3711     \end_deeper
3712     \begin_layout List
3713     \labelwidthstring 00000.00000.00000.000
3714 jpye 1384
3715     \family sans
3716 johnpye 828 real_constant
3717 jpye 1384 \family default
3718    
3719 jpye 1733 \begin_inset LatexCommand index
3720     name "real\\_constant"
3721 johnpye 828
3722     \end_inset
3723    
3724     Real number with dimensionality.
3725     Note that the dimensionality of a real constant can be specified via the
3726     type definition without immediately defining the value, as in the following
3727     pair of definitions.
3728     \end_layout
3729    
3730     \begin_layout List
3731     \labelwidthstring 00000.00000.00000.000
3732    
3733     \bar under
3734     CONSTANT\InsetSpace ~
3735     declaration\InsetSpace ~
3736     example:
3737     \end_layout
3738    
3739     \begin_deeper
3740     \begin_layout LyX-Code
3741     CONSTANT molar_weight
3742     \end_layout
3743    
3744     \begin_layout LyX-Code
3745     REFINES real_constant DIMENSION M/Q;
3746     \end_layout
3747    
3748     \begin_layout LyX-Code
3749     CONSTANT hydrogen_weight
3750     \end_layout
3751    
3752     \begin_layout LyX-Code
3753     REFINES molar_weight :== 1.004{g/mole};
3754     \end_layout
3755    
3756     \end_deeper
3757     \begin_layout List
3758     \labelwidthstring 00000.00000.00000.000
3759 jpye 1384
3760     \family sans
3761 johnpye 828 integer_constant
3762 jpye 1384 \family default
3763    
3764 jpye 1733 \begin_inset LatexCommand index
3765     name "integer\\_constant"
3766 johnpye 828
3767     \end_inset
3768    
3769     Integer number.
3770     Principally used in determining model structure.
3771     If appearing in equations, integers are evaluated as dimensionless reals.
3772 jpye 1384 Typical use is inside a
3773     \family sans
3774     MODEL
3775     \family default
3776     definition and looks like:
3777 johnpye 828 \end_layout
3778    
3779     \begin_deeper
3780     \begin_layout LyX-Code
3781     n_trays IS_A integer_constant;
3782     \end_layout
3783    
3784     \begin_layout LyX-Code
3785     n_trays :== 50;
3786     \end_layout
3787    
3788     \begin_layout LyX-Code
3789     tray[1..n_trays] IS_A vl_equilibrium_tray;
3790     \end_layout
3791    
3792     \end_deeper
3793     \begin_layout List
3794     \labelwidthstring 00000.00000.00000.000
3795 jpye 1384
3796     \family sans
3797 johnpye 828 symbol_constant
3798 jpye 1384 \family default
3799    
3800 jpye 1733 \begin_inset LatexCommand index
3801     name "symbol\\_constant"
3802 johnpye 828
3803     \end_inset
3804    
3805     Object with a symbol value.
3806     May be used in determining model structure.
3807     \end_layout
3808    
3809     \begin_layout List
3810     \labelwidthstring 00000.00000.00000.000
3811 jpye 1384
3812     \family sans
3813 johnpye 828 boolean_constant
3814 jpye 1384 \family default
3815    
3816 jpye 1733 \begin_inset LatexCommand index
3817     name "boolean\\_constant"
3818 johnpye 828
3819     \end_inset
3820    
3821     Logical value.
3822     May be used in determining model structure.
3823     \end_layout
3824    
3825     \begin_layout List
3826     \labelwidthstring 00000.00000.00000.000
3827    
3828     \bar under
3829     Setting\InsetSpace ~
3830     constants
3831     \bar default
3832    
3833 jpye 1733 \begin_inset LatexCommand index
3834     name "constants, setting"
3835 johnpye 828
3836     \end_inset
3837    
3838    
3839     \end_layout
3840    
3841     \begin_layout List
3842     \labelwidthstring 00000.00000.00000.000
3843     :==
3844 jpye 1733 \begin_inset LatexCommand index
3845     name ":=="
3846 johnpye 828
3847     \end_inset
3848    
3849     Constant and set assignment operator.
3850    
3851     \end_layout
3852    
3853     \begin_deeper
3854     \begin_layout Standard
3855     It is suggested, but not required, that names of all types that refine the
3856     built-in constant types have names that end in _constant.
3857     \end_layout
3858    
3859     \begin_layout LyX-Code
3860     LHS_list :== RHS;
3861     \end_layout
3862    
3863     \begin_layout Standard
3864     Here it is required that the one or more items in the LHS be of the same
3865     constant type and that RHS is a single-valued expression made up of values,
3866     operators, and other constants.
3867 jpye 1384 The
3868     \family typewriter
3869     :==
3870     \family default
3871     is used to make clear to both the user and the system what scalar objects
3872     are constants.
3873 johnpye 828
3874     \end_layout
3875    
3876 jpye 1384 \begin_layout Section
3877 johnpye 828 Variables
3878 jpye 1733 \begin_inset LatexCommand index
3879     name "variables"
3880 johnpye 828
3881     \end_inset
3882    
3883    
3884     \end_layout
3885    
3886     \begin_layout Standard
3887     There are four built-in types which may be used to construct variables:
3888     symbol, boolean, integer, and real.
3889     At this time symbol types have special restrictions.
3890 jpye 1384 Refinements of these variable base types are defined with the
3891     \family sans
3892     ATOM
3893     \family default
3894     statement.
3895 johnpye 828 Atom types may declare attribute fields with types real, integer, boolean,
3896     symbol, and set.
3897 jpye 1384 These attributes are
3898     \emph on
3899     not
3900     \emph default
3901     independent objects and therefore cannot be refined, merged, or put in
3902     a refinement clique (
3903     \family sans
3904     ARE_ALIKE
3905     \family default
3906     d).
3907 johnpye 828 \end_layout
3908    
3909     \end_deeper
3910     \begin_layout List
3911     \labelwidthstring 00000.00000.00000.000
3912 jpye 1384
3913     \family sans
3914 johnpye 828 ATOM
3915 jpye 1384 \family default
3916    
3917 jpye 1733 \begin_inset LatexCommand index
3918     name "ATOM"
3919 johnpye 828
3920     \end_inset
3921    
3922     The syntax for declaring a new atom type is
3923     \end_layout
3924    
3925     \begin_deeper
3926     \begin_layout LyX-Code
3927     ATOM
3928     \emph on
3929     atom_type_name
3930     \emph default
3931     REFINES
3932     \emph on
3933     variable_type
3934     \end_layout
3935    
3936     \begin_layout LyX-Code
3937 jpye 1733 «DIMENSION
3938 johnpye 828 \emph on
3939     dimension_expression
3940     \emph default
3941 jpye 1733 »
3942 johnpye 828 \end_layout
3943    
3944     \begin_layout LyX-Code
3945 jpye 1733 «DEFAULT
3946 johnpye 828 \emph on
3947     value
3948     \emph default
3949 jpye 1733 »; (* note the ; *)
3950 johnpye 828 \end_layout
3951    
3952     \begin_layout LyX-Code
3953 jpye 1733 «
3954 johnpye 828 \emph on
3955     initial attribute assignment
3956     \emph default
3957 jpye 1733
3958 johnpye 828 \end_layout
3959    
3960     \begin_layout LyX-Code
3961     END
3962     \emph on
3963     atom_type_name
3964     \emph default
3965     ;
3966     \end_layout
3967    
3968     \end_deeper
3969     \begin_layout List
3970     \labelwidthstring 00000.00000.00000.000
3971 jpye 1384
3972     \family sans
3973 johnpye 828 DEFAULT
3974 jpye 1384 \family default
3975    
3976 jpye 1733 \begin_inset LatexCommand index
3977     name "DEFAULT"
3978 johnpye 828
3979     \end_inset
3980    
3981 jpye 1384 ,
3982     \family sans
3983     \InsetSpace ~
3984 johnpye 828 DIMENSION
3985 jpye 1384 \family default
3986    
3987 jpye 1733 \begin_inset LatexCommand index
3988     name "DIMENSION"
3989 johnpye 828
3990     \end_inset
3991    
3992     ,\InsetSpace ~
3993     and\InsetSpace ~
3994 jpye 1384
3995     \family sans
3996 johnpye 828 DIMENSIONLESS
3997 jpye 1384 \family default
3998    
3999 jpye 1733 \begin_inset LatexCommand index
4000     name "DIMENSIONLESS"
4001 johnpye 828
4002     \end_inset
4003    
4004    
4005     \end_layout
4006    
4007     \begin_deeper
4008     \begin_layout Standard
4009 jpye 1384 The
4010     \family sans
4011     DIMENSION
4012     \family default
4013     attribute is for variables whose base type is real.
4014 johnpye 828 It is an optional field.
4015     If not defined for any atom with base type real, the dimensions will be
4016     left as undefined.
4017     Any variable which is later declared to be one of these types will be given
4018     wild card dimensionality (represented in the interactive display by an
4019     asterisk (*)).
4020     The system will deduce the dimensionality from its use in the relationships
4021     in which it appears or in the declaring of default values for it, if possible.
4022     \end_layout
4023    
4024     \end_deeper
4025     \begin_layout List
4026     \labelwidthstring 00000.00000.00000.000
4027 jpye 1384
4028     \family sans
4029 johnpye 828 solver_var
4030 jpye 1384 \family default
4031    
4032 jpye 1733 \begin_inset LatexCommand index
4033     name "solver\\_var"
4034 johnpye 828
4035     \end_inset
4036    
4037 jpye 1384 is a special case of