Some insights about building Models in EMSO

Hello everyone,

In this post I am going to talk about the general structure used for building Models in EMSO. This post includes topics such as: (1) how to declare parameters and variables, (2) how to write equations, and (3) how to specify parameters, variables and/or initial conditions. In this post I will also cover in-depth those topics that were briefly mentioned in the previous post (Creating your first mathematical model in EMSO).

For creating Models in EMSO, we must follow a general structure in EMSO (aka  Model Entity). For the sake of simplicity, we can understand this structure as if we were filling the different fields of a form. So let’s take a look at the general Model structure (click on the image to zoom):

Model StructureImage footnotes: (1) Instructions in square brackets ( [  ] ) are optional.              (2) Words such as {Par/Var/Folder}Name, Base, Text, Value, etc. are used along the code as templates that the user has to edit.

In this structure we can identify a main entity known as Model, which is basically enclosed by two keywords Model and end. We must write our model in the space comprised between them. You will be probably wondering how to write a model. Well, inside the Model entity can exist  several sections, which – each one by itself – allows us to set a different part of the model. Such sections are: ATTRIBUTES, PARAMETERS, VARIABLES, EQUATIONS, SET, SPECIFY, and INITIAL.
As you will notice, not all of them will be always required, because that will depend on the type of model you are going to build. You must include at least one section in the model. In this sense, all those sections are optional. So let’s analyse each of them. I will leave the ATTRIBUTES section to the end, so we can understand it better once the other ones had been covered.

The PARAMETERS section

As I mentioned in the aforementioned post, this section allows us to declare the different parameters of the model. Each parameter must have a name, a base type, and some attributes (See the keywords between parentheses in the previous image). Parameter names cannot start with a number nor having spaces between letters. With respect to the base types, you can find all of them in the EMSO_QuickRef.pdf file provided in the EMSO installation folder. All the parameter attributes are optional, you don’t have to specify all of them, because each base type in EMSO already has default values for each attribute. Please refer to the image above to read descriptive comments about the use of each attribute. The qualifier keyword outer (before the parameter name) is also optional and is used to specify external parameters as we will see in future posts.

The VARIABLES section

This section is quite similar to the PARAMETERS one. The main difference is in which attributes and qualifier keywords they can take. At first, let’s analyse the attributes. As you can see in the model structure image shown previously, there are some attributes in common between variables and parameters (e.g. Brief, Default, Lower, Upper, Unit, and DisplayUnit). A variable can also take other attributes such as PosX, PosY, and LineDashed. These ones are either positional or formatting attributes as you will understand clearly when you read about the ATTRIBUTES section. With respect to the qualifier keywords in and out, they will also be discussed in the ATTRIBUTES section.

The EQUATIONS section

This section is used to declare the different equations of the model. Each equation to be declared can also include a name. This feature allows to you find easily the equations through the Explorer panel when having very large models. Although the order of writing equation is irrelevant, we should consider some tips for avoiding problems such as mathematical indeterminacies. With the main end of avoiding indeterminacies related to fractions in an equation, please try always to avoid the use of denominators. You can eliminate them by multiplying the equation as many times as needed to be done.

The SET and INITIAL sections

These sections are used to specify parameters, variables and initial conditions, respectively. They are quite similar.

In the SET section you can specify a value to those parameters whose values are not set yet (or we want to change their default values). This can be done by writing the parameter name on the left-hand side of the equal sign (=) and a numerical value or a mathematical expression involving only parameters on the right-hand side. This section applies only for parameters.

The INITIAL section is used to specify the initial conditions of the first-order ordinary differential equations in the model. Whenever you use the diff( ) function over an unknown variable, you must specify an initial condition in the INITIAL condition section. Its functionality is quite similar to the SET one, but with the difference that, it can also take a name for the expression as we saw previously with the EQUATIONS section. Additionally, it can receive both numerical values and mathematical expression in its right-hand side.

It does also exist a section called SPECIFY, which can be  used too (sometimes impractical) and is very similar to the SET one, but it applies only for variables and can be used only to specify numerical values, not mathematical expressions. This will be covered in detail in future posts when we talk about FlowSheets.

The ATTRIBUTES section

This section is used only when we want to create models to be used primarily in the Diagram interface, i.e., models we want to assign a representative block for being used graphically in the EMSO Palette. This section is constituted by several attributes we can assign to a model. In this post we will cover just three of them: Icon, Pallete (it must be used as stated, although the correct english word, Palette induces us not to), and Info.

The Icon keyword receives the actual location of the image to be used for representing the model in the palette. The location must be written between quotes. It is recommended to create a folder (called icon, images, etc.) in the same folder where the model is saved and store your images in it. This allows you to put some order when building several models.

The Pallete keyword is an attribute that receives a boolean value (true or false) for telling EMSO whether it should show the model in the EMSO palette or not.

The Info keyword is used to specify detailed information about the model functionality. This attibute is primarily intended for the user, who wants to generate automatically the model documentation in LATEX format.

Now we can understand the function of the qualifier keywords in and out, the positional attributes PosX, PosY, and the formatting attribute LineDashed. The in and out qualifiers allow us to create variables which are going to be used as input and output ports in the model, respectively. PosX and PosY are called positional attributes, because they designate the position of the input/output ports in the graphical representation of the model. In EMSO, every image used to represent graphically a model it is interpreted by EMSO as a rectangular box, whose sides are ranged between 0 and 1, as the following figure shows:

ModelImageMapping

The LineDashed attribute is used for telling EMSO to use a dashed line to represent a physical connection of this model through this port with the port of another model.

CONCLUDING REMARKS

  • Almost all lines of code end with a semicolon (;).
  • EMSO was created using an object-oriented paradigm. In this sense, variables, parameters, models, flowsheets, etc. are considered as objects, indeed. A clear evidence of this is the keyword as, which says to a specific object to behave as (or to inherit the behaviour of) another one. This feature is known as inheritance and can also be used with entities such as Model, FlowSheet, etc. This means that the word Base in the model structure image can represent indeed a type base, a Model, a FlowSheet, etc., as we will see in future posts.
  • All the unstated attributes in the model will take the their default values.

I hope this post can solve the doubts that users normally have about creating models in EMSO. I my next post I will try to put these concepts altogether in an illustrative example.

If you have a doubt, just let me know in the comments.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: