Guidelines for model-writing

This page will contain some guidelines for model-writing with ASCEND, specifically oriented towards the use of the newer PyGTK-based GUI. This supplements the more detailed material given in the users' manual (see the documentation page). Feel free to add any further comments/suggestions/advice here.

Object-oriented naming

Model names should be concise and represent things whereever possible, as opposed to processes or actions. So, for example, you might write a model car_dynamic rather than a model acceleration_and_braking.

Note that if you have a model file "mymodel.a4c", then if it contains a model named "mymodel", that model will by default be instantiated when the model file is loaded. This is handy in many cases, because normally a model file with have a 'main purpose' that you mostly open it for. So use this default naming to make your model file easier to use.

Variable naming

ASCEND is essentially a mathematical modelling language. As equations quickly become complex, it is important that variables are named in a way that makes the resulting equations readable. It is preferable, therefore, to use standard abbreviations and symbols like h (for enthalpy) wherever possible, rather than the more typical computer-science approach of longVariableNamesDescribingWhatTheyAreFor.

Occasionally we come across cases where people from different backgrounds have different 'standard symbols'. In those cases, we tend to err towards the english/american standards from engineering textbooks. For energy systems modelling, textbooks like Holman, Cengel, and Moran & Shapiro give the general flavour.

Setting your parameters

The preferred way to set parameters in your model is to FIX them and then assign a value to them in a suitable METHOD. The quick-and-dirty way is to use an on_load method. A more sophisticated way is to use a specify method and a values methods. This makes reusing your model easier, because someone who wants to incorporate your model as a submodel in a larger problem can create an instance of your model then run the necessary methods on it, as part of their own model's methods.

Default values and initial guesses

It is recommended to write a default_self method in your model, which should be called from your on_load method. Any variables that need to be initialised to other than their internally-defined default value can then be assigned their. Note that these are not FIXed variables; these are variables that will be solved for, but when set to a good first guess, will solve much more readily, with less iterations.

Flowsheet modelling

Is is suggested, tentatively, that components in a flowsheet be given short abbreviated names in two or three capital letters, suffixed with a number if necessary, eg TU1 for Turbine 1, or PU2 for Pump 2. These short names are usually sufficiently memorable, but succinct enough to keep your model readable without excessive typing.

Use of parametric models

In ASCEND, it is possible to write models that require parameters in order to be instantiated. With our canvas-based modeller, we have currently found some difficulty in making use of such models, because of the difficulty that arises with the use of ARE_THE_SAME to merge variables in such cases. So for reusable block models, we are currently preferring the use of non-parametric models, although that might change in the future.

Model testing

It is advisable when writing models to also develop simple 'test models' that instantiate the model you have just written, and set its parameters for a typical set of conditions. This model should solve easily, and should contain a self_test METHOD that includes various ASSERT statements to check that solved variables have the expected values. This aids greatly in debugging and maintaining models for future use.

on_load behaviour

Ideally, when a model file is loaded with the PyGTK GUI, it should immediately put itself into a solvable state. One should be able to load a model, click 'solve' and have some useful results. The power comes next, when the user can manually tweak the values of any variables in the model, to obtain results for new/different problems.