= EMSO Language Changes Suggestions =

== '''ext''' keyword for ''global'' parameters ==

Currently the '''ext''' keyword is used to obtain a ''global'' parameter.
I've observed that this keyword is not well suited for its meaning.

The idea from http://www.modelica.org is to have '''outer''' parameters, which means a parameter from one of the ''parents''.
Then the simulator will look for the parameter in the '''parent tree''' until it finds it (maybe it is found only on the FlowSheet but it can be matched before).

Usage example:
{{{
#!mso
Model stream
	PARAMETERS
	outer NComp as Integer(Brief = "Number of chemical components", Lower = 1); 

	VARIABLES
	F as flow_mol;
	T as temperature;
	P as pressure;
	z(NComp) as fraction (Brief = "Overall Molar Fraction");
	h as enth_mol (Brief = "Overall Molar Enthalpy");
	v as fraction (Brief = "Vapourisation fraction");
end

FlowSheet MyProcess
	PARAMETERS
	NComp as Integer(Brief = "Number of chemical components", Lower = 1);

	DEVICES
	feed as stream;
end
}}}

Then when '''feed''' is instantiated on the FlowSheet '''feed.NComp''' will be a reference for '''NComp''' on the FlowSheet.
But if the stream is used in a model this model can have a '''NComp''' parameter and this will be referenced.

||Who || Opinion || Why ||
||Rafael || '''agreed''' || proposed the change ||
||Paula || '''agreed''' || because this change gives more flexibility to the user ||
||Arge || '''in doubt''' || if two streams are used in a model with different number of '''NComp''', is it possible to set '''stream1.NComp''' and '''stream2.NComp''' to different values in that model? ||

== CalcObject's ==

This is another example of keyword which is not directly understood by the users.
I suggest to use just '''Plugin''' instead of '''CalcObject'''.

Usage:
{{{
#!mso
Model stream_therm as stream
	PARAMETERS
	outer  PP   as Plugin(Brief = "External Physical Properties", File="vrpp");
	
	EQUATIONS
	h = (1-v)*PP.LiquidEnthalpy(T, P, z) + v*PP.VapourEnthalpy(T, P, z);
end
}}}

Another problem with the Plugin's is that each Plugin '''call''' (e.g. '''PP.LiquidEnthalpy(T, P, z)''') generates a units of measurement warning.
In order to solve this problem I suggest the specification of the '''File''' attribute even for '''outer''' Plugins (as exemplified above).
Then the simulator can check the units of measurement and number of arguments when checking the model and not only when the simulation is run.

||Who || Opinion || Why ||
||Rafael || '''agreed''' || proposed the change ||
||Paula || '''agreed''' || because the warnings about unit checked in models cause a bad impression ||
||Arge || '''partially agreed''' || the name '''Plugin''' is fine, but the obligation of the '''File''' specification turns the Plugins less pluggable (unless they could be overwritten) ||

== Repository Directory Layout ==

This is not exactly a change on the language, but in order to support a change on the language we will need a '''branch''' on the models repository.

Usually, SVN repositories follow the layout:
 * trunk (the main development)
 * branches (the branches for parallel development with the trunk)
   * branch1
   * branch2
   * etc

In order to implement this change we could just rename the '''mso''' directory on the repository to '''trunk''' and create another top folder called '''branches'''.

||Who || Opinion || Why ||
||Rafael || '''agreed''' || proposed the change ||
||Paula || '''agreed''' || branches to test the latest language modifications ||
||Arge || '''agreed''' || safer solution ||

== Model Attributes ==

Currently only '''types''' have attributes, examples:
{{{
#!mso
positive as Real (Brief = "Positive General Constant", Default=1.0, Lower=-1e-6);
negative as Real (Brief = "Negative General Constant", Default=-1.0, Upper=0.0);
fraction as positive (Brief = "Fraction" , Default=0.5, Upper=1.00001);
}}}

In the above type declarations, '''Brief''', '''Lower''', etc are attributes.
We are planning to add attributes also for '''Model'''s and we need to define a syntax for their declaration.

=== Option 1 ===

Something similar to the types declaration:
{{{
#!mso
Model MyTankModel (Icon="Tank", IconSize="normal", Brief="Model for a special kind of tank",
    Documentation="The model documentation. This should be more detailed than Brief,
    possibly spanning in multiple lines.
    It also should be good a have some wiki formating support in the documentation.
    Then we can have the library of models documentation automatically built based on it.")
    PARAMETERS
    ...
    VARIABLES
    ...
end
}}}

=== Option 2 ===

A new section for setting the attributes:
{{{
#!mso
Model MyTankModel
    ATTRIBUTES
    Icon="Tank";
    IconSize="normal";
    Brief="Model for a special kind of tank";
    Documentation="The model documentation. This should be more detailed than Brief,
    possibly spanning in multiple lines.
    It also should be good a have some wiki formating support in the documentation.
    Then we can have the library of models documentation automatically built based on it.";

    PARAMETERS
    ...
    VARIABLES
    ...
end
}}}

=== Option 3 ===

Leave the attributes handling to the graphical interface (as gPROMS does), then:
 * Models remain as they are today
 * The user edits graphically:
   * which models appear on the '''pallet'''
   * the documentation of the model (probably with a graphical editor with support for '''bold''', ''italics'', lists, etc
   * which variables should appear on results
   * which variables can be specified or not (this can be even refined supporting ''specification sets'')
   * which is the icon for the model
   * the relative position where the ports are shown

All the information configured graphically by the user can be stored in a XML file on the same folder of the models.

||Who || Opinion || Why ||
||Rafael || '''option 3''' || With option 3 we have a clear distinction between the graphical interface and the models ||
||Paula ||'''option 2''' || Because the graphical interface is so far from a usable version and with option 2 a parser can be made to automaticaly generate the documentation in pdf, wiki and to the graphical interface ||
||Arge ||'''option 2''' || In agreement with Paula's comment about parsers and also because the graphical interface can overwrite those attributes and store them in a XML file of the flowsheet without changing the library models ||

== Switcher for equations ==

Currently, continuous-discrete modeling is supported in EMSO using the '''if''' statement.
But some more complex situations cannot be modeled with '''if'''.

For example, a safety valve which opens if the pressure is higher than 2 atm but closes only when the pressure is lower than the outside pressure.
This situation cannot be modeled by a simply '''if'''. For this case, a State Transition Network (STN) is needed.

For this case the '''Switcher''' is proposed, usage:
{{{
#!mso
Model SafetyValve
    PARAMETERS
    ValveMode as Switcher(Valid = ["closed", "opened"], Default = "closed")
    ...
    EQUATIONS
    switch ValveMode
    case "closed":
       flow = 0 * "mol/h";
       change to "opened" if P > 2*"atm";
    case "opened":
       flow = k*sqrt(P - Pout);
       change to "closed" if P < Pout;
    end
    ...
end
}}}

In the piece of code above there are the following news:
 * A new basic type called '''Switcher'''
 * The '''Switcher''' type has an extra attribute called '''Valid''' which are the valid values for the switcher
 * There is a '''switch''' command which can be used in the EQUATIONS
 * There is a '''change to''' command which can be used inside a '''case''' of a '''switch'''. NOTE: the '''change to''' command is optional, if the '''change to''' command is missing then the '''case''' is a '''black hole''': there is no way to get out! :)

||Who || Opinion || Why ||
||Rafael || '''agreed''' || proposed the change ||
||Paula || '''agreed''' || is very usefull to overcome the limitations in '''if''' structure ||
||Arge || '''agreed''' || very important resource ||

== Units Of Measurement (UOM) ==

Currently EMSO support Units Of Measurement (UOM) for variables, parameters, equations, etc.
The problem is that the units of measurement are declared exactly as string text (with double quotes, eg "kg/h")

I think it should be a good idea to directly distinguish texts from UOM in some way:
 * We could use the simple quote for UOM, eg. 'kg/h'
 * We could use the '''{''', eg. {kg/h}

||Who || Opinion || Why ||
||Rafael || '''in doubt''' || I still don't know which is the better way to distinguish a Text from a UOM ||
||Arge || '''agreed''' || Single quote seems to be the better solution, and it helps to distinguish an equation name from an UOM at the beginnig of an expression ||

== OPTIONS section ==

Currently EMSO support few common options for the solvers, such as '''relativeAccuracy''' and '''absoluteAccuracy'''. However, each solver has its own specific design options.
I suggest the following:

{{{
#!mso
FlowSheet Myflowsheet
    ...
    OPTIONS
     time = [0:0.1:30];
     relativeAccuracy = 1e-8;
     absoluteAccuracy = 1e-9;
     DAESolver = "dasslc" {"maxorder" = 5, "maxlen" = 400};
end
}}}

||Who || Opinion || Why ||
||Arge || '''agreed''' || proposed the change ||