View source

{{ThinWalledNavigation}}
In this part, we continue the example we introduced in Part 1.  Our goal is to provide an introductory tutorial into using the ASCEND modeling environment.  We shall show how to add METHODS to models to make them more useful for sharing with others and/or with oneself at a later time.

== Introduction: making a model sharable==

We shall say a model is sharable if one can use and understand it without being its developer.  Being able to solve a model at least one time without first understanding it can aid significantly in learning about the model, especially in a modeling environment such as ASCEND that allows one to explore a solved model instance in detail.

In Part 1, our ASCEND model was a nonprocedural listing of the variables and equations that must be true at the model solution.  There were no statements as to how to solve the model.  We know that solving large nonlinear models can be very difficult numerically and can require the modeler to provide a lot of special knowledge to coerce the model to a solution.  We want to add this knowledge to the code defining the model without forcing a modeler to use that knowledge when using the same model in a different manner - such as to solve for a different set of fixed variables or when embedding the model as a part of a larger model.  

Our approach in ASCEND is to allow modelers to add any number of methods to a model.  Methods are executable procedures that can alter the values of the variables and flags within a model instance and that can trigger the execution of other methods.  One writes them within within a [[METHODS]] section for the model.

== Adding methods to the thin-walled tank model ==

The following is our thin walled tank example with an added [[METHODS]] section.

<source lang="a4c" tabwidth=4>
(* this is file twt0210.a4c *)
REQUIRE "atoms.a4l";

MODEL thin_walled_tank;

    (* fixed variables *)
    D,
    H,
    wall_thickness  IS_A distance;
    metal_density   IS_A mass_density;
 
    (* computed variables *)
    end_area,
    side_area       IS_A area; 
    wall_vol        IS_A volume;
    metal_mass      IS_A mass;
  
    (* equations *)
    end_area=3.1416*D^2/4;
    side_area=3.1416*D*H;
    wall_vol=(side_area+2*end_area)*wall_thickness;
    metal_mass=metal_density*wall_vol;

METHODS

   METHOD specify;
      FIX D;
      FIX H;
      FIX wall_thickness;
      FIX metal_density;
   END specify;

   METHOD values;
      D              := 20.0 {cm};
      H              := D/10.0;
      wall_thickness := 0.15 {cm};
      metal_density  := 7.85 {g/cm^3};
   END values;

   METHOD setup;
      RUN specify;
      RUN values;
   END setup;
 
END thin_walled_tank;
</source>

We include three methods: specify - to set the fixed flags for the fixed variables, values - to provide values for these four fixed variables and setup - to trigger the running of the other two methods.  A user of this model within the TclTK interface would load it, compile it, and export it to the solver.  With a tool within the solver, he would trigger the method "setup" to run.  Finally he would solve the well-posed model.  Note that he could do all these steps without understanding anything about the model.  When done, he would have a solved model instance that he could then examine in detail using many of the available tools.

A method is a procedure.  Thus statements that set values for the variables are of the general form 

<source lang="a4c" tabwidth=4>
  LHS variable := RHS expression;
</source>

This statement states that ASCEND is to replace the value of the LHS variable with the current value of the RHS expression.  The replacement equals (:=) is not the equation equals (=) that we used in the nonprocedural part of our model.

==Discussion==

Note that the METHODS section provides procedures a model user can invoke only when he wishes.  Running "setup" blindly sets up his model for solving.  As the original modeler will have tested this model before making it available, he would know that running "setup" creates a model instance that will solve.  He has thus passed this information along to the subsequent user, making the model more sharable than before.

Also note that the second user of this model does not need to use any of these methods.  It is still a model he could play with interactively in many other ways.  It has just provided him with one way to get a first solution to examine.

==Standardized set of methods==

We advise modelers using ASCEND to develop a number of different methods for a model.  That these methods exist and are useful is supported by our experiences with using ASCEND.  Note that no method has to be there.  We give several of these methods standard names, and both the TclTk and PyGTK interfaces discover and trigger some of these methods automatically when compiling and solving a model.  A significant difference between the two interfaces is the number of methods each expects and triggers automatically, with the PyGTK using methods as a means to make one's first experience with a model appear to be very simple.  We describe here the methods these interfaces anticipate being in a model.

See also [[METHODS]].

Continue with [[Thin-walled tank/Building_complex_models|the next section, Building complex models]]

[[Category:Examples]]
[[Category:Tutorials]]