#LyX 1.4.1 created this file. For more info see http://www.lyx.org/ \lyxformat 245 \begin_document \begin_header \textclass book \language english \inputencoding auto \fontscheme default \graphics default \paperfontsize default \spacing single \papersize a4paper \use_geometry false \use_amsmath 2 \cite_engine basic \use_bibtopic false \paperorientation portrait \secnumdepth 3 \tocdepth 3 \paragraph_separation indent \defskip medskip \quotes_language english \papercolumns 1 \papersides 2 \paperpagestyle default \tracking_changes false \output_changes true \end_header \begin_body \begin_layout Chapter Writing METHODs \begin_inset LatexCommand \label{cha:methods} \end_inset \end_layout \begin_layout Standard In this chapter we describe a methodology (pun intended) which can help make anyone who can solve a quadratic equation a mathematical modeling expert. This methodology helps you to avoid mistakes and to find mistakes quickly when you make them. Finding bugs weeks after creating a model is annoying, inefficient, and (frequently) embarrassing. Because METHOD code can be large, we do not include many examples here. \begin_inset Note Note status collapsed \begin_layout Standard See ***vessel something*** for detailed examples \end_layout \end_inset One of the advantages of this methodology is that it allows almost automatic \begin_inset LatexCommand \index{methods, automatic generation} \end_inset generation of methods for a model based on the declarative structure (defined parts and variables) in the model, as we shall see in Section\InsetSpace ~ \begin_inset LatexCommand \ref{sec:methods.automation} \end_inset \noun off . Even if you skip much of this chapter, read \noun default Section\InsetSpace ~ \noun off \begin_inset LatexCommand \ref{sec:methods.automation} \end_inset \end_layout \begin_layout Standard We divide methods into \family typewriter _self \family default and \family typewriter _all \family default categories. The premise of our approach to design methods is that we can write the \family typewriter _self \family default methods incrementally, building on the already tested methods of previous MODEL parts we are reusing. In this way we never have to write a single huge method that directly manipulat es the hundreds of variables that are in the model hierarchy. Were that all there was to it, things would actually be pretty simple. However, in ASCEND, one can also select to solve any part of an ASCEND model (in particular, any part that is an instance of a single type), and this capability complicates method writing - but not by much if we really understand the approach we advocate here. As an example, suppose we have a flowsheet that has a reactor followed by a flash unit in it. In ASCEND, we can select to solve the entire flowsheet, only the reactor, only the flash unit or even any one of the streams in it (yes, each stream has physical property calculations that belong to it making it interesting to isolate and solve). Should we choose to solve only the flash unit, ASCEND will isolate the equations defining the flash - including the equations we use when defining the input and output streams to it as they are a part of the flash unit. But the input to the flash is also the output from the reactor and is a part of the reactor, too. Each part would typically take the prime responsibility for supplying methods that will set fix flags, set nominal values, etc., for its variables, but who owns the variables they both share such as in the connecting stream? By \begin_inset Quotes eld \end_inset tradition \begin_inset Quotes erd \end_inset in chemical engineering flowsheet modeling, we will assert that the reactor has prime responsibility for its output stream. If we are solving the entire flowsheet, it should set the flags, etc., for its output stream. However, when we isolate the flash for solving, the flash unit must assume responsibility to set fix flags, nominal values, etc., for the output stream from the reactor as that stream is its input stream. The \family typewriter _all \family default methods allow us to handle these shared variables correctly when we isolate a part for solving by itself. \begin_inset Note Note status collapsed \begin_layout Standard This needs more explanation: I don't find it completely clear. \end_layout \end_inset \end_layout \begin_layout Standard Usually discovery of the information you need to write the methods proceeds in the order that they appear below: \family typewriter check \family default , \family typewriter default \family default , \family typewriter specify \family default , \family typewriter bound \family default , \family typewriter scale \family default . \end_layout \begin_layout Section Why use standardised methods on models? \end_layout \begin_layout Standard In the present chapter, we are proposing that you use a particular standardised set of methods on your models. While ASCEND doesn't force you to follow these conventions, we hope that you will \emph on choose \emph default to follow them, because: \end_layout \begin_layout Itemize You models will be more portable. \end_layout \begin_layout Itemize They will integrate better with the existing model library when composing larger models composed of smaller perhaps pre-existing models. \end_layout \begin_layout Itemize Other users will be be more easily able to understand what you have built. \end_layout \begin_layout Itemize The proposed structure has, in our experience, made for models that are easier to debug. \end_layout \begin_layout Standard There will be cases where these standard methods don't suffice for your needs; these are just proposals for a useful starting point and shared-use conventions. \end_layout \begin_layout Standard Note that if you do not write the standard methods, your MODEL will inherit the ones given in the library \family typewriter basemodel.a4l \family default . The \family typewriter ClearAll \family default and \family typewriter reset \family default methods here will work for you if you follow the guidelines for the method \family typewriter specify \family default . The other methods defined in \family typewriter basemodel.a4l \family default \family typewriter (check_self \family default , \family typewriter default_self \family default , \family typewriter bound_self \family default , \family typewriter scale_self \family default , \family typewriter check_all \family default , \family typewriter default_all \family default , \family typewriter bound_all \family default , \family typewriter scale_all \family default ) all contain \family typewriter STOP \family default statements that will warn you that you have skipped something important, should you accidentally call one of these methods. If you create a model for someone else and they run into one of these \family typewriter STOP \family default errors while using your model, that error is your fault. \end_layout \begin_layout Section Methods *_self \begin_inset LatexCommand \index{methods, \_self} \end_inset VS *_all \begin_inset LatexCommand \index{methods, \_all} \end_inset \end_layout \begin_layout Standard When you create a model definition, you create a container holding variables, equations, arrays, and other models. You create methods in the same definition to control the state of (the values stored in) all these parts. ASCEND lets you share objects among several models by passing objects through a model interface (the \family typewriter MODEL \family default parameter list), by creating ALIASES \begin_inset LatexCommand \index{ALIASES} \end_inset for parts within contained objects, and even by merging parts (though merging should be avoided for any object larger than a variable). \end_layout \begin_layout Standard \begin_inset Marginal status collapsed \begin_layout Standard Too many cooks \begin_inset LatexCommand \index{cooks} \end_inset spoil the broth \begin_inset LatexCommand \index{broth} \end_inset . \end_layout \end_inset The problem this creates for you as a \family typewriter METHOD \family default writer is to decide which of the several \family typewriter MODEL \family default s that share an object is responsible for updating that variable's default, bounds, and nominal values. You could decide that every model which shares a variable is responsible for these values. This decision will lead to many, many, many hard to understand conflicts as different models all try to manage the same value. And, the last one run will in fact have the final say. But it is difficult to know always which is the last one run. The sensible approach is to make only one model responsible for the bounding, scaling, and default setting of each variable: \emph on the model that creates the variable in the first place \emph default . If you abide by this approach, you will keep things much simpler for yourself. And, fortunately, the modeling language makes it pretty clear who has created each and every variable - except when merging variables. \end_layout \begin_layout Standard \begin_inset Marginal status collapsed \begin_layout Standard Use *_self methods on locally created variables and parts \end_layout \end_inset Consider the following model and creating the \family typewriter *_self \family default methods \family typewriter default_self \family default , \family typewriter check_self \family default , \family typewriter bound_self \family default , and \family typewriter scale_self \family default for it. \end_layout \begin_layout LyX-Code MODEL selfish( \end_layout \begin_layout LyX-Code external_var WILL_BE solver_var; \end_layout \begin_layout LyX-Code out_thingy WILL_BE input_part; \end_layout \begin_layout LyX-Code ); \end_layout \begin_layout LyX-Code my_variable IS_A solver_var; \end_layout \begin_layout LyX-Code \end_layout \begin_layout LyX-Code peek_at_variable ALIASES out_thingy.mabob.cost; \end_layout \begin_layout LyX-Code my_thingy IS_A nother_part; \end_layout \begin_layout LyX-Code navel_gaze ALIASES my_thingy.mabob.cost; \end_layout \begin_layout LyX-Code END selfish; \end_layout \begin_layout Standard \end_layout \begin_layout Standard \family typewriter IS_A \family default statements indicate all the parts we have created in this model: namely, the \family typewriter solver_var \family default we call \family typewriter my_variable \family default and the \family typewriter nother_part \family default we call \family typewriter my_thingy \family default . This model should manage the value of the only variable it creates: \family typewriter my_variable \family default . The variable, \family typewriter external_var \family default , comes in from the outside so some other model has created it and should manage it. The variables \family typewriter peek_at_variable \family default and \family typewriter navel_gaze \family default also are not created here and should not be managed in the \family typewriter *_self \family default methods of \family typewriter selfish \family default . \family typewriter my_thingy.mabob.cost \family default belongs to a part we created. We want to default, bound, or scale variables in all parts we create, also, so we must call \family typewriter my_thingy.default_self \family default whenever \family typewriter default_self \family default is called for this model. Its \family typewriter *_self \family default method should in turn call the \family typewriter *_self \family default method for \family typewriter mabob \family default , which should set defaults, bounds and scaling for its variable, \family typewriter cost \family default . Finally, \family typewriter out_thingy \family default is an input parameter and is not created here; we should not call \family typewriter out_thingy.default_self \family default , therefore, as some other model will do so. \end_layout \begin_layout Standard \begin_inset Marginal status collapsed \begin_layout Standard Use *_all methods to manage a troublesome part \end_layout \end_inset As noted above, you may choose to isolate any mathematical subproblem in a large simulation for debugging or solving purposes. When you do this isolation using the Browser and Solver tools, you still need to call scaling, bounding, and checking methods for all parts of the isolated subproblem, even for those parts that come in from the outside. This is easily done by writing \family typewriter *_all \family default methods. In the example above, \family typewriter scale_all \family default will scale \family typewriter external_var \family default and call \family typewriter out_thingy.scale_all \family default because these parts are defined using \family typewriter WILL_BE \family default \begin_inset LatexCommand \index{WILL\_BE} \end_inset statements. Finally \family typewriter scale_all \family default will call its local \family typewriter *_self \family default to do all the normal scaling. \end_layout \begin_layout Standard That's the big picture of \family typewriter *_self \family default and \family typewriter *_all \family default methods. Each kind of method (bound, scale, default, check) has its own peculiarities, which we cover in Section \begin_inset LatexCommand \ref{sec:methods.selfMethods} \end_inset \noun off and \noun default Section \noun off \begin_inset LatexCommand \ref{sec:methods.allMethods} \end_inset , but they all follow the rules above \noun default and \noun off distinguish among variables and parts defined with \family typewriter \noun default WILL_BE \family default \noun off (managed in * \family typewriter \noun default _all \family default \noun off only), IS_A \begin_inset LatexCommand \index{IS\_A} \end_inset (managed in \family typewriter \noun default *_self \family default \noun off only), and \family typewriter \noun default ALIASES \family default \noun off (not our responsibility). \end_layout \begin_layout Section How to write ClearAll \begin_inset LatexCommand \index{ClearAll} \end_inset and reset \begin_inset LatexCommand \index{reset} \end_inset \end_layout \begin_layout Standard Writing these two standard methods in your model is very simple: do nothing. You may wish to write alternative \family typewriter reset_* \family default methods as we shall discuss. All models inherit these methods from the definitions in \family typewriter basemodel.a4l \family default . Just so you know, here is what they do. \end_layout \begin_layout Subsection \family typewriter METHOD ClearAll \end_layout \begin_layout Standard This method finds any variable that is a \family typewriter solver_var \family default or refinement of \family typewriter solver_var \family default and changes the \family typewriter .fixed \family default flag on that var to \family typewriter FALSE \family default . This method only touches the \family typewriter .fixe \family default d flags; i.e., it does not change the value of \family typewriter .included \family default flags on relations or return boolean, integer and symbol variables to a default value. \end_layout \begin_layout Subsection \family typewriter METHOD reset \end_layout \begin_layout Standard This method calls \family typewriter ClearAll \family default to bring the model to a standard state with all variables unfixed (free), then it calls the user-written specify method to bring the model to a state where it has an equal number of variables to calculate and equations to solve - i.e., to being \begin_inset Quotes eld \end_inset square. \begin_inset Quotes erd \end_inset Normally you do not need to write this method: your models will inherit this one unless you override it (redefine it) in your model. \end_layout \begin_layout Standard This standard state is not necessarily the most useful starting state for any particular application. This method merely establishes a base case the modeler finds to be a good starting point. As an example, the modeler may elect to set fix variables for the base case for a flash unit so it corresponds to an isothermal flash calculation. Chemical engineers understand this case and can make changes from it to set up other cases, such as an adiabatic flash, relatively easily by setting and resetting but one or two \family typewriter .fixed \family default flags. There is no one perfect "reset"' for all purposes. Other \family typewriter reset_* \family default methods can also be written for particular purposes, if such arise \begin_inset Foot status collapsed \begin_layout Standard The name of a method, for example \family typewriter reset_someOtherPurpose \family default is a communication tool. Please use meaningful names as long as necessary to tell what the method does. Avoid cryptic abbreviations and hyper-specialized jargon known only to you and your three friends when you are naming methods; however, do not shy away from technical terms common to the engineering domain in which you are modeling. \end_layout \end_inset . \end_layout \begin_layout Section The \family typewriter *_self \family default \begin_inset LatexCommand \index{\_self} \end_inset methods \begin_inset LatexCommand \label{sec:methods.selfMethods} \end_inset \end_layout \begin_layout Standard The following methods should be redefined by each reusable library \family typewriter MODEL \family default . Models that do not supply proper versions of these methods are usually very hard to reuse. \end_layout \begin_layout Subsection \family typewriter METHOD check_self \family default \begin_inset LatexCommand \index{check\_self} \end_inset \end_layout \begin_layout Standard One can benefit by writing this method first, though it is run last. Just as they taught you in elementary school, always check your work. Start by defining criteria for a successful solution that will not be included in the equations solved and compute them in this method. As you develop your \family typewriter MODEL \family default , you should expect to revise the check method from time to time, if you are learning anything about the model. We frequently change our definition of success when modeling. \end_layout \begin_layout Standard When a mathematical model is solved, the assumptions that went into writing (deriving) the equations should be checked. Usually there are redundant equations available (more than one way to state the physics or economics mathematically). These should be used to check the particularly tricky bits of the model. \end_layout \begin_layout Standard Check that the physical or intuitive (qualitative) relationships among variables you expect to hold are true, especially if you have not written such relationsh ips in terms of inequalities ( \family typewriter x*z <= y \family default ) in the \family typewriter MODEL \family default equations. \end_layout \begin_layout Standard In some models, checking the variable values against absolute physical limits ( \family typewriter temperature > 0{K} \family default and \family typewriter temperature < Tcritical \family default , for example) may be all that is necessary or possible. Do not check variable values against their \family typewriter .lower_bound \family default or \family typewriter .upper_bound \family default , as ASCEND will do this for you. \end_layout \begin_layout Standard If a check fails, use a \family typewriter STOP \family default \begin_inset LatexCommand \index{STOP} \end_inset statement to notify yourself (or your end-user) that the solution may be bogus. \family typewriter STOP \family default raises an error signal and issues an error message. \family typewriter STOP \family default normally also stops further execution of the method and returns control to a higher level, though there are interactive tools to force method execution to continue. \family typewriter STOP \family default does not cause ASCEND to exit though: just for the method execution to halt and for control to return to the user. \end_layout \begin_layout Subsection \family typewriter METHOD default_self \begin_inset LatexCommand \index{default\_self} \end_inset \end_layout \begin_layout Standard This method should set default values for any variables declared locally ( \family typewriter IS_A \family default ) to the model. If the default value declared for the atom type, of which the variable is an instance, is appropriate (and typically it is), then you need not set a specific default value here. This method also should run \family typewriter default_self \family default on all the complex parts that are declared locally (with \family typewriter IS_A \family default ) in the model. \end_layout \begin_layout Standard This method should not run any methods on model parts that come via \family typewriter WILL_BE \family default in the definition's parameter list. This method also should not change the values of variables that are passed in through the parameter list. Sometimes there will be nothing for this method to do. Define it anyway, leaving it empty, so that any writer reusing this model as part of a higher level model can safely assume it is there and call it without having to know the details. \end_layout \begin_layout Standard When a top-level simulation is built by the compiler, this method will be run (for the top-level model) at the end of compilation. If your model's \family typewriter default_self \family default method does not call the lower-level \family typewriter default_self \family default methods in your model locally-declared ( \family typewriter IS_A \family default ) parts, it is quite likely that your model will not solve. \end_layout \begin_layout Subsection \family typewriter METHOD bound_self \begin_inset LatexCommand \index{bound\_self} \end_inset \end_layout \begin_layout Standard Much of the art of nonlinear physical modeling is in bounding the solution. This method should update the bounds on locally defined ( \family typewriter IS_A \family default ) variables and \family typewriter (IS_A) \family default defined model parts. Updating bounds requires some care. For example, the bounds on fractions frequently don't need updating. This method should not bound variables passed into the \family typewriter MODEL \family default definition or parts passed into the definition. \end_layout \begin_layout Standard A common formula for updating bounds is to define a region around the current value of the variable. A linear region size formula, as an example, would be: \end_layout \begin_layout Standard \begin_inset Formula \begin{equation} x_{bound}=x\pm\Delta\cdot x_{nominal}\label{eq:methods.bound-width}\end{equation} \end_inset or, in ASCEND syntax, \end_layout \begin_layout LyX-Code v.upper_bound := v + \begin_inset LatexCommand \index{boundwidth} \end_inset boundwidth * v.nominal; \end_layout \begin_layout LyX-Code v.lower_bound := v - boundwidth * v.nominal; \end_layout \begin_layout Standard Care must be taken that such a formula does not move the bounds (particularly lower bounds) out so far as to allow non-physical solutions. Logarithmic bounding regions are also simple to calculate. Here \family typewriter boundwidth \family default is a \family typewriter bound_width \family default : it could be a real atom (but \series bold not \series default a \family typewriter solver_var \family default ) or some value you can use to determine how much "wiggle-room" you want to give a solver. \end_layout \begin_layout Standard Small powers of 4 and 10 are usually good values of \family typewriter boundwidth \family default . Too small a boundwidth can cut off the portion of number space where the solution is found. Too large a bound width can allow solvers to wander for great distances in uninteresting regions of the number space. \end_layout \begin_layout Standard \begin_inset Note Note status open \begin_layout Standard We need an example here \end_layout \end_inset \end_layout \begin_layout Subsection \family typewriter METHOD scale_self \begin_inset LatexCommand \index{scale\_self} \end_inset \begin_inset LatexCommand \label{ssec:methods.scaleself} \end_inset \end_layout \begin_layout Standard Most nonlinear (and many linear) models cannot be solved without proper scaling of the variables. \family typewriter scale_self \family default should reset the \family typewriter .nominal \family default value on every real variable in need of scaling. It should then call the \family typewriter scale_self \family default method on all the locally-defined ( \family typewriter IS_A \family default ) parts of the MODEL. A proper nominal is one such that you expect at the solution \end_layout \begin_layout Standard \begin_inset Formula \begin{equation} 0\leq abs\left(\frac{x}{x_{nominal}}\right)\leq10\label{eq:methods.choiceNominal}\end{equation} \end_inset \end_layout \begin_layout Standard As one is dividing by the nominal value for the variable to establish its scaled value, zero is about the worst value you could choose for a nominal value. \end_layout \begin_layout Standard This method should not change the \family typewriter .nominal \family default values for models and variables that are received through the parameter list of the model. \end_layout \begin_layout Standard Variables (like fractions), when bounded such that they cannot be too far away from 1.0 in magnitude, probably don't need scaling most of the time, so long as they they are also bounded away from 0.0. \end_layout \begin_layout Standard Some solvers, but not all, will attempt to scale the equations and variables by heuristic matrix-based methods. This works, but inconsistently; user-defined scaling \begin_inset LatexCommand \index{scaling} \end_inset is generally superior. ASCEND makes scaling equations easy to do. You scale the variables, which can only be done well by knowing something about where the solution is going to be found (by being an engineer, for example). Then ASCEND can calculate an appropriate equation-scaling by efficient symbolic methods. \end_layout \begin_layout Section The \family typewriter *_all \family default methods \begin_inset LatexCommand \label{sec:methods.allMethods} \end_inset \end_layout \begin_layout Subsection \family typewriter METHOD default_all \begin_inset LatexCommand \index{default\_all} \end_inset \end_layout \begin_layout Standard Above we discussed the ability in ASCEND to isolate and solve any part of a model that is defined as an instance of a single type requires you initialize the arguments to a model that you are isolating. This method should run the \family typewriter default_all \family default method on each of the parts received through the parameter list via \family typewriter WILL_BE \family default statements and should give appropriate default values to any variables received through the parameter list. After these calls and settings have been done, it should then call its own \family typewriter default_self \family default to take care of all local defaults. \end_layout \begin_layout Subsection \family typewriter METHOD check_all \begin_inset LatexCommand \index{check\_all} \end_inset \end_layout \begin_layout Standard When solving only a part of a simulation, it is necessary to check the models and variables passed into the part as well as the locally defined parts and variables. This method should call \family typewriter check_all \family default on the parts received as \family typewriter WILL_BE \family default parameters, then call \family typewriter check_self \family default to check the locally defined parts and equations. \end_layout \begin_layout Subsection \family typewriter METHOD bound_all \begin_inset LatexCommand \index{bound\_all} \end_inset \end_layout \begin_layout Standard This method should be like \family typewriter bound_self \family default except that it bounds the passed in variables and calls \family typewriter bound_all \family default on the passed in parts. It should then call \family typewriter bound_self \family default . \end_layout \begin_layout Subsection \family typewriter METHOD scale_all \begin_inset LatexCommand \index{scale\_all} \end_inset \end_layout \begin_layout Standard This method should be like \family typewriter scale_self \family default above except that it scales the variables received through the parameter list and calls \family typewriter scale_all \family default on the passed in parts. It should then call \family typewriter scale_self \family default to take care of the local variables and models. \end_layout \begin_layout Section \family typewriter METHOD specify \family default \begin_inset LatexCommand \index{specify} \end_inset \end_layout \begin_layout Standard The method \family typewriter specify \family default sets the \family typewriter .fixed \family default flags so an instance of the model is solvable. There are two issues involved. First, the model must be square - i.e., it must have as many free variables as it has eligible equations available to compute them. Second, it should be a setting of \family typewriter .fixed \family default flags that the modeler knows will solve numerically. This latter requirement requires one to have an intuitive feel for the model. A chemical engineer will \begin_inset Quotes eld \end_inset know \begin_inset Quotes erd \end_inset that a flash calculation, where he has fixed both the pressure and the vapor fraction, is a pretty robust calculation. It would be a good way to set fix flags in the \family typewriter specify \family default method. Getting the \family typewriter .fixed \family default flags set for a large complex model is one of the hardest tasks ever invented by mathematicians if you go about it in the wrong way. If you follow the prescription here, getting the right number of flags set is almost automatic. We have set written the specify methods for a complex hierarchy of models correctly the first time using this approach. \end_layout \begin_layout Standard We shall illustrate this section by examining the set of models in \family typewriter simple_fs.a4c \family default . You should find that model in the model directory for ASCEND and open it in your favorite text editor. This model is for a simple flowsheet comprising a mixer, a reactor, a flash unit and a simple stream splitter. It contains the following models: \family typewriter mixture \family default , \family typewriter molar_stream \family default , \family typewriter mixer \family default , \family typewriter reactor \family default , \family typewriter flash \family default , \family typewriter splitter \family default , \family typewriter flowsheet \family default , \family typewriter controller \family default , \family typewriter test_flowsheet \family default and \family typewriter test_controller \family default . When compiling and solving, one typically creates an instance of \family typewriter test_controller \family default . \end_layout \begin_layout Standard Model mixture only defines new variables \family typewriter y[components] \family default and one equation that says their sum is unity. Model molar_stream introduces new variables \family typewriter Ftot \family default and \family typewriter f[components] \family default . It also introduces an instance of the model mixture, which it calls \family typewriter state \family default . Finally it introduces locally the equations \family typewriter f_def \family default , one for each component. Models \family typewriter mixer \family default , \family typewriter reactor \family default , \family typewriter flash \family default and \family typewriter splitter \family default introduce their own local variables and equations. Each also defines it input and output streams as instances of the model \family typewriter molar_stream \family default . Model \family typewriter flowsheet \family default contains a \family typewriter mixer \family default , \family typewriter reactor \family default , \family typewriter flash \family default and \family typewriter splitter \family default , etc. \end_layout \begin_layout Standard Assume you have just written a set of models, such as those in \family typewriter simple_fs.a4c \family default . In this approach you should start with the lowest level models - i.e., the ones that only introduce (using \family typewriter IS_A \family default statements) new variables and new parts that are instances of types in existing ASCEND libraries. The lowest level model by this definition is \family typewriter mixture \family default . It only introduces new variables and one new equation. Once you have written and debugged a \family typewriter specify \family default method for \family typewriter mixture \family default , then again look for any model that only introduces new variables and local equations and/or parts for which a debugged \family typewriter specify \family default method exists. The model \family typewriter molar_stream \family default is such a model and can be considered next. It introduces a part which is an instance of \family typewriter mixture \family default for which we already have a \family typewriter specify \family default method. Once we have a debugged \family typewriter specify \family default method for \family typewriter molar_stream \family default , then we can consider any of the models \family typewriter mixer \family default , \family typewriter reactor \family default , \family typewriter flash \family default and \family typewriter splitter \family default - they only have parts that are instances of \family typewriter molar_stream \family default . After creating and debugging their \family typewriter specify \family default methods, we can consider the model \family typewriter flowsheet \family default , then \family typewriter controller \family default , then \family typewriter test_flowsheet \family default and finally \family typewriter test_controller \family default . \end_layout \begin_layout Standard The safest way to set \family typewriter .fixed \family default flags is first to clear all the \family typewriter .fixed \family default flags for a model instance by running the method \family typewriter ClearAll \family default . The method \family typewriter specify \family default does \series bold not \series default run \family typewriter ClearAll \family default , but we always write our \family typewriter specify \family default methods assuming \family typewriter ClearAll \family default has just been run and thus that all \family typewriter .fixed \family default flags are set to false. The following steps will aid you to write, almost automatically, a \family typewriter specify \family default method that fixes the correct number of \family typewriter .fixed \family default flags. \end_layout \begin_layout Enumerate Find all locally defined solver variables (of type \family typewriter solver_var \family default - e.g., \family typewriter y[components] \family default are of type \family typewriter fraction \family default which is of type \family typewriter solver_var \family default ). In mixture, the statement \begin_inset Quotes eld \end_inset \family typewriter y[components] IS_A fraction; \family default \begin_inset Quotes erd \end_inset introduces new \family typewriter solver_var \family default s, one for each element in the set \family typewriter components \family default . Let us assume there are \family typewriter nc \family default such elements. \end_layout \begin_layout Enumerate Find locally introduced equations. In \family typewriter mixture \family default , there is one such equation that says the variables \family typewriter y \family default add up to one. \end_layout \begin_layout Enumerate Find all new parts that are instances of previously defined types. In \family typewriter mixture \family default , there are no new parts. \end_layout \begin_layout Enumerate You must set \family typewriter .fixed \family default flags locally equal in number to the number of new locally defined \family typewriter solver_var \family default s minus the number of new locally defined equations. In \family typewriter mixture \family default you must write set one \family typewriter fixed \family default flag to true for all but one of the components as there are \family typewriter nc \family default new locally introduced variables and one new locally introduced equation. The \family typewriter CHOICE \family default function arbitrarily selects one element of the set (in set theory, you cannot identify a set element as being first, another as second, etc, so for purity's sake, we only give you the option of letting ASCEND pick one arbitrarily). Thus we set all \family typewriter nc \family default flags and then clear one. \end_layout \begin_layout Enumerate You must run the \family typewriter specify \family default method for each new part. Here there are none. Running specify will guarantee each part is \begin_inset Quotes eld \end_inset square \begin_inset Quotes erd \end_inset - i.e., after being run, the part will not alter the number of degrees of freedom for the current model definition. However, the same \family typewriter solver_var \family default may get fixed in two or more different parts if those parts share that \family typewriter solver_var \family default , and you will have to discover this sharing and add special statements to correct this type of multiple setting of the same flag. This discovery will best be done by compiling an instance of the type and using the Find By Type tool in the Browser. Its default setting is to find all \family typewriter solver_vars \family default with \family typewriter .fixed \family default equal to \family typewriter TRUE \family default , exactly what you need to aid you with this task. You may also wish to change in minor ways the flag setting that the parts do to suit the needs of the current type definition - you may wish to free \family typewriter temperature \family default and fix \family typewriter pressure \family default for a stream, for example, when the stream is part of a higher level model. \end_layout \begin_layout Standard Look now at the \family typewriter molar_stream \family default model. Running \family typewriter ClearAll \family default for an instance of \family typewriter molar_stream \family default will clear all the \family typewriter .fixed \family default flags for it and all its parts. It introduces \family typewriter Ftot \family default and \family typewriter f[components] \family default as local new solver variables. It also introduces one new equation for each component, one less than the number of new variables. Finally it introduces a new part called \family typewriter state \family default . We have partitioned the \family typewriter specify \family default method into two methods here for \begin_inset Quotes eld \end_inset chemical engineering reasons, \begin_inset Quotes erd \end_inset one of which runs the other. Think of what the two of them accomplish as the \family typewriter specify \family default method we wish to create. First we run the \family typewriter specify \family default method for the new part: \family typewriter state \family default . That will set the \family typewriter .fixed \family default flags for \family typewriter nc-1 \family default of the variables \family typewriter state.y[components] \family default . Then, as there is one more variable than equation in this model, we must set a net of one added \family typewriter .fixed \family default flag. We accomplish this by first clearing all the flags for the variables \family typewriter state.y[components] \family default -- one of which was already clear -- and then fixing all the variables \family typewriter f[components] \family default . We cleared \family typewriter nc-1 \family default flags and set \family typewriter nc \family default for a net of one new flag being set. For our \family typewriter molar_stream \family default model, we would prefer that the variables \family typewriter f[components] \family default are the ones we fix. \end_layout \begin_layout Standard Lastly, look at the \family typewriter reactor \family default model. We introduce \family typewriter nc+1 \family default new variables: \family typewriter stoich_coef[feed.components] \family default and \family typewriter turnover \family default . We also introduce \family typewriter nc \family default new equations. Lastly we introduce two parts \family typewriter feed \family default and \family typewriter out \family default , which are \family typewriter molar_stream \family default s. The \family typewriter specify \family default method, again a combination of \family typewriter specify \family default and \family typewriter seqmod \family default , must set a net of one new \family typewriter .fixed \family default flag. The way it does it is \begin_inset Quotes eld \end_inset tricky \begin_inset Quotes erd \end_inset but not difficult to follow. In \family typewriter seqmod \family default , we fix \family typewriter turnover \family default and all \family typewriter nc \family default of the variables \family typewriter stoich_coef \family default . We seem to have fixed \family typewriter nc \family default too many. In \family typewriter specify \family default , which first runs \family typewriter seqmod \family default , we only run the \family typewriter specify \family default method for \family typewriter feed \family default and \series bold not \series default the \family typewriter specify \family default method for \family typewriter out \family default . We know that not running the \family typewriter specify \family default method for \family typewriter out \family default , a \family typewriter molar_stream \family default as we just discussed above, will leave us with \family typewriter nc \family default \family typewriter .fixed \family default flags not set. So we deviously traded these flags for those belonging to \family typewriter stoich_coef \family default , giving us a net of fixing one flag. If we had abided by all the steps above, we would have run the \family typewriter specify \family default method for \family typewriter out \family default , then gone in and cleared the flags for \family typewriter out.f[components] \family default while setting those for \family typewriter stoich_coef[components] \family default in trade to get the flags we want set for this model. We did the equivalent with a shortcut. \end_layout \begin_layout Standard If a model is parametric, the models defined by \family typewriter WILL_BE \family default in the parameter list should be viewed as new variables defined in the model. Remember \family typewriter specify \family default must fix sufficient variables to make an instance of this model square. \end_layout \begin_layout Standard At each of the above steps, pay special attention to indexed variables used in \emph on indexed \emph default equations \begin_inset Note Note status collapsed \begin_layout Standard need a cross reference here to the appropriate part of the manual \end_layout \end_inset . Frequently you must fix or free \family typewriter n \family default or \family typewriter n-1 \family default variables indexed over a set of size \family typewriter n \family default , if there are \family typewriter n \family default matching equations. In general, if you think you have \family typewriter specify \family default correctly written, change the sizes of all the sets in your MODEL by one and then by two members. If your \family typewriter specify \family default method still works, you are probably using sets correctly. Pursuing 'symmetry', i.e. the identical treatment of all variables defined in a single array, usually helps you write \family typewriter specify \family default correctly. \end_layout \begin_layout Standard When writing models that combine parts which do not share very well, or which both try to compute the same variable in different ways, it may even be necessary to write a \family typewriter WHEN \family default statement to selectively 'turn off' the conflicting equations or model fragments. An object or equation \family typewriter USE \family default d in any \family typewriter WHEN \family default statement is turned off by default and becomes a part of the solved \family typewriter MODEL \family default only when the condition of some \family typewriter CASE \family default that \family typewriter USE \family default s that object is matched. \end_layout \begin_layout Standard The setting of boolean, integer, and symbol variables that are controlling conditions of \family typewriter WHEN \family default and \family typewriter SWITCH \family default statements should be done in the \family typewriter specify \family default method. \end_layout \begin_layout Standard There is no 'one perfect' \family typewriter specify \family default method for all purposes. This routine should merely define a reasonably useful base configuration of the model. Other \family typewriter specify_whatElseYouWant \family default methods can also be written. \end_layout \begin_layout Section \family typewriter METHOD values \begin_inset LatexCommand \index{values} \end_inset \end_layout \begin_layout Standard In a final application \family typewriter MODEL \family default , you should record at least one set of input values (values of the fixed variables and guesses of key solved-for variables) that leads to a good solution. This facilitates testing of the model, and helps the next person using your model to be assured that it works as expected. \end_layout \begin_layout Section Summary \end_layout \begin_layout Standard \begin_inset Marginal status collapsed \begin_layout Standard adding our standard methods to a model definition \end_layout \end_inset We have defined a set of standard methods for ASCEND models which we insist a modeler provide before we will allow a model to be placed in any of our model libraries. These are listed in Table \begin_inset LatexCommand \ref{tab:methods.stdMethodReqd} \end_inset \noun off . As should be evident from above, not all models must have associated methods; our first vessel model did not. It is simply our policy that models in our libraries must have these methods to promote model reuse and to serve as examples of best practices in mathematic al modeling. \end_layout \begin_layout Standard \begin_inset Float table wide false sideways false status open \begin_layout Caption \begin_inset LatexCommand \label{tab:methods.stdMethodReqd} \end_inset Standard methods required for types in our ASCEND model library \end_layout \begin_layout Standard \begin_inset Tabular \begin_inset Text \begin_layout Standard method \end_layout \end_inset \begin_inset Text \begin_layout Standard description \end_layout \end_inset \begin_inset Text \begin_layout Standard \family typewriter default_self \end_layout \end_inset \begin_inset Text \begin_layout Standard a method called automatically when any simulation is compiled to provide default values and adjust bounds for any locally created variables which may have unsuitable defaultsin their ATOM definitions. Usually the variables selected are those for which the model becomes ill-behave d if given poor initial guesses or bounds (e.g., zero). This method should include statements to run the default_self method for each of its locally created (IS_A'd) parts. This method should be written first. \end_layout \end_inset \begin_inset Text \begin_layout Standard \family typewriter ClearAll \end_layout \end_inset \begin_inset Text \begin_layout Standard a method to set all the fixed flags for variables in the type to FALSE. This puts these flags into a known standard state -- i.e., all are FALSE. All models inherit this method from the base model and the need to rewrite it is very, very rare. \end_layout \end_inset \begin_inset Text \begin_layout Standard \family typewriter specify \end_layout \end_inset \begin_inset Text \begin_layout Standard a method which assumes all the \family typewriter fixed \family default flags are currently \family typewriter FALSE \family default and which then sets a suitable set of fixed flags to \family typewriter TRUE \family default to make an instance of this type of model well-posed. A well-posed model is one that is square ( \begin_inset Formula $n$ \end_inset equations in \begin_inset Formula $n$ \end_inset unknowns) and solvable. \end_layout \end_inset \begin_inset Text \begin_layout Standard \family typewriter reset \end_layout \end_inset \begin_inset Text \begin_layout Standard a method which first runs the \family typewriter ClearAll \family default method and then the \family typewriter specify \family default method. We include this method because it is very convenient. We only have to run one method to make any simulation well-posed, no matter how its fixed flags are currently set. All models inherit this method from the base model, as with \family typewriter ClearAll \family default . \end_layout \end_inset \begin_inset Text \begin_layout Standard \family typewriter values \end_layout \end_inset \begin_inset Text \begin_layout Standard a method to establish typical values for the variables we have fixed in an application or test model. We may also supply values for some of the variables we will be computing to aid in solving a model instance of this type. These values are ones that we have tested for simulation of this type and found good. \end_layout \end_inset \begin_inset Text \begin_layout Standard \family typewriter bound_self \end_layout \end_inset \begin_inset Text \begin_layout Standard a method to update the \family typewriter .upper_bound \family default and \family typewriter .lower_bound \family default value for each of the variables. ASCEND solvers use these bound values to help solve the model equations. This method should bound locally created variables and then call \family typewriter bound_self \family default for every locally created ( \family typewriter IS_A \family default 'd) part. \end_layout \end_inset \begin_inset Text \begin_layout Standard \family typewriter scale_self \end_layout \end_inset \begin_inset Text \begin_layout Standard a method to update the \family typewriter .nominal \family default value for each of the variables. ASCEND solvers will use these nominal values to rescale the variable to have a value of about one in magnitude to help solve the model equations. This method should re-scale locally created variables and then call \family typewriter scale_self \family default for every locally created ( \family typewriter IS_A \family default 'd) part. \end_layout \end_inset \end_inset \end_layout \end_inset \end_layout \begin_layout Section Method writing automation \begin_inset LatexCommand \label{sec:methods.automation} \end_inset \end_layout \begin_layout Standard \begin_inset Marginal status collapsed \begin_layout Standard Hit the button Library/Edit/Suggest methods and tweak the results \end_layout \end_inset ASCEND will help you write the standard methods. Writing most of the standard methods can be nearly automated once the declarati ve portion of the model definition is written. Usually, however, some minor tweaking of the automatically generated code is needed. In the Library window, the Edit menu has a "Suggest methods" button. Select a model you have written and read into the library, then hit this button. \end_layout \begin_layout Standard In the Display window will appear a good starting point for the standard methods that you have not yet defined. This starting point follows the guidelines in this chapter. It saves you a lot of typing but it is a starting point only. Select and copy the text into the model you are editing, then tailor it to your needs and finish the missing bits. The comments in the generated code can be deleted before or after you copy the text to your model file. \end_layout \begin_layout Standard If you have suggestions for general improvements to the generated method code, please mail them to us and include a sample of what the generated code ought to look like before the user performs any hand-editing. We aim to create easily understood and easily fixed method suggestions, not perfect suggestions, because procedural code style tastes vary so widely. \end_layout \begin_layout Standard \begin_inset Note Note status open \begin_layout Standard Closing the chapter you find below the suggested methods ASCEND generates for the ***vessel*** model. \end_layout \end_inset \end_layout \end_body \end_document