# Contents of /trunk/doc/howto-atoms.lyx

updating RPM spec for Fed20

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